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
          example: Peter
        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
          example: Asian
        dateOfBirth:
          type: string
          example: '1980-05-27'
          description: ISO DOB in form of yyyy-MM-dd
        nameSuffix:
          type: string
          description: jr, II
          example: Jr
        nationality:
          type: string
          example: Belgian
        preferredLanguage:
          type: string
          example: English
        address:
          type: string
          example: 123 Yellobrick Lane
        city:
          type: string
          example: Chicago
        region:
          type: string
          description: >-
            should match regions configured in the volunteer configuration
            component; ie state / province
          example: Chicago
        country:
          type: string
          example: US
        postalCode:
          type: string
          example: 60657
        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
          example: +1312 554 1218
        workPhone:
          type: string
          description: see homePhone
          example: +1312 554 1218
        mobilePhone:
          type: string
          description: same rules apply as homePhone, but must be unique in database
          example: +1312 554 1218
        phoneNotes:
          type: string
          description: can be arbitrary notes to guide recruiters about making phone calls
          example: 
        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
          example: Joseph Smith
        generalPractitionerPhoneNumber:
          type: string
          description: volunteer's physician phone number
          example: +1312 555 1212
        descriptiongeneralPractitionerAddress:
Customer ID assigned by the service provider   - urltype: 'https://{ngrokPrefix}.ngrok.io/clinspark/api/v1/recruit'string
    variables:       ngrokPrefix:
 description: volunteer's physician address
      default: 04f5b951df6d   example: 232 Yellobrick Lane
  description: first part of ngrok-assigned id pathssiteName:
  /saveVolunteer:      post:  type: string
   tags:       example: Base -Site
recruit       summary: Saves a newdescription: volunteer>-
      operationId: saveVolunteer     the name requestBody:of the site that the volunteer should be associated content:with;
          application/json:  if not provided, use siteId
      schema:  siteId:
          type: integer
$ref: '#/components/schemas/Volunteer'         descriptionformat: JSON volunteerinteger
to add         requiredexample: -1
true       responses:   description: >-
    '200':        the id of description: 'Success: OK message.'
    the site that the volunteer should be associated with; if
   '401':         not provided, description: 'Unauthorized: Must add Basic Authentication headers'use siteName
        paymentStrategy:
    '422':        type: string
 description: >-          enum:
  Invalid request: There are input validation errors; look at the JSON  - IBAN
         response for details.   - ABA
  security:         - basicAuthexample: []IBAN
   /findActiveStudySites:     getibanAccount: 
     tags:     type: string
  - recruit       summaryexample: ES9121000418450200051332
Finds study sites that are actively recruiting    description: Used if parameters:IBAN is chosen as Payment Strategy. Validated using iban4j.org
-  name: studyName     ibanBank:
     in: query    type: string
     description: >-    example: CAIXESBB666
       Case insensitive study namedescription: usedUsed toif matchIBAN studyis siteschosen withas thePayment Strategy. Validated using iban4j.org
        corresponding nameabaAccount:
          requiredtype: falsestring
          schemaexample: 123456789
           typedescription: stringUsed if ABA is chosen as Payment Strategy. Validated -using name:ABANumberCheckDigit siteIdlibrary.
          inabaBank: query
          descriptiontype: string
>-          example: 021000021
 ID of a given site; only study sites with thedescription: correspondingUsed siteif ABA is chosen as Payment Strategy. Validated using ABANumberCheckDigit library.
  will be returned    previousStudyParticipation:
      required: false   type: boolean
      schema:  volunteerAnswers:
          type: array
number          example:
  format: int64         - namequestion: siteNameFavorite web    application?
     in: query           description: >-
answer: Gmail
           Case insensitive- sitequestion: nameFavorite usednumber?
to match study sites with the         answer: '123'
  corresponding name         - question: required:Favorite falsedecimal?
          schema:    answer: '123.4'
       type: string    - question: Favorite date?
 - name: locationOid           inanswer: query'1969-07-20'
          description: >-
            Casearray sensitiveof locationsimple OIDobjects usedwith toverbatim matchClinSpark studyquestions sitesand
with the             corresponding OIDanswers
          requireditems:
 false           schema:$ref: '#/components/schemas/VolunteerAnswer'
        volunteerNotes:
          type: array
string        responses:  example:
      '200':      - Volunteer travels often
 description: successful operation         - Is content:afraid of needles
          application/jsondescription: Simple notes that move to a volunteer notes section
      schema:    items:
            type: arraystring
        volunteerRaces:
       items:   type: array
          example:
    type: object       - American Indian or Alaska Native
      properties: {}   description: Must match race security:names defined in ClinSpark
     - basicAuth: []   /findUnassignedAppointmentsitems:
    get:        tagstype: string
       - recruitvolunteerSubstanceUse:
      summary: Finds appointments for the given study sitetype: array
      parameters:    example:
    - name: studySiteId      - substanceUseCategory: Alcohol
  in: query           descriptionname: ID ofBeer
a given study site           requireduseFrequency: trueWeek
          schema:    useConsumption: '5'
       type: number      consumptionUnit: Glass/Bottle (.5L)
    format: int64         - namesubstanceUseStatus: cohortNameSocial
          in: query   startDate: '2001'
      description: >-       lastConsumed: '2021-07-21'
    Case insensitive cohort name used for a wild card search; onlysubstanceNotes: Enjoys heavy IPAs
         appointments thatdescription: have>-
an assigned cohort matching will be returned       array of simple objects required:with falseverbatim ClinSpark questions and
       schema:     corresponding answers
      type: string   items:
     - name: appointmentType     $ref: '#/components/schemas/VolunteerSubstanceUse'
    inVolunteerUpdate:
query      type: object
   description: >-  properties:
        id:
 Case insensitive appointment typed used for a wild card search;type: onlyinteger
          format: integer
appointments that have an apointment type matching will be returnedexternalId:
          requiredtype: falsestring
          schemaexample: '987123'
           typedescription: stringUnique identifier in originating recruitment   responses:system
        '200'title:
          descriptiontype: string
successful  operation        example: Mr
 content:       firstName:
     application/json:     type: string
        schema:  example: Joseph
        middleName:
    type: array     type: string
          itemsdescription: >-
            can be an initial, if $ref: '#/components/schemas/RecruitmentAppointment'
        '400':no value is provided a '-' will be stored with
           description: Invalidthe usernamevolunteer suppliedreocord
        '404'lastName:
          descriptiontype: string
 User not found       securityexample: Padres
       - basicAuthgenderMale:
[]     /listVolunteerAppointments:     gettype: boolean
     tags   ethnicHispanic:
        - recruit  type: boolean
   summary: >-      description: null indicates Findsunknown
appointments for the given volunteer found by one ofotherRace:
the         parameters suppliedtype: string
     parameters:     description: additional race details -if name:race externalIdtype doesn't match
        indateOfBirth:
query           descriptiontype: IDstring
from source system        example: '1980-05-27'
 required: false        description: ISO DOB schema:in form of yyyy-MM-dd
         typenameSuffix:
string         - nametype: emailAddressstring
          indescription: queryjr, II
         descriptionnationality:
Case insensitive email address           requiredtype: falsestring
          schemapreferredLanguage:
 
          type: string
        - nameaddress: mobilePhone
          intype: querystring
        city:
 description: Will be converted to ISO format before a query takestype: placestring
        region:
 required: false        type: string
 schema:         description: >-
  type: string       responses:  should match regions configured in the volunteer '200':configuration
          description: successful operationcomponent; ie state / province
      content:  country:
          application/jsontype: string
        postalCode:
    schema:      type: string
        homePhone:
type: array         type: string
      items:    description: >-
            tightly $ref: '#/components/schemas/RecruitmentAppointment'
        '400':validated based on the general settings configured; should
            be description:as Invalidclose usernameto suppliedISO format as possible with leading country code.
 '404':           description: User not foundhttps://github.com/google/libphonenumber is used for underlying
       security:     validation
   - basicAuth: []   /assignAppointmentworkPhone:
    post:       tagstype: string
       - recruit  description: see homePhone
  summary: Allows for assigning a given appointmentmobilePhone:
to a matching volunteer       parameterstype: string
       - name: recruitmentAppointmentId description: same rules apply as homePhone, but must be unique in: querydatabase
          descriptionphoneNotes:
ID from source system           requiredtype: truestring
          schemadescription: can be arbitrary notes to guide recruiters about making phone  calls
type: number       contactableByPhone:
     format: int64    type: boolean
   - name: externalId     description: volunteer's permission to be contacted in:by queryphone
          descriptiondefault: IDtrue
from source system      contactableBySms:
    required: false     type: boolean
    schema:      description: volunteer's permission to be contacted by type:SMS
string         - namedefault: emailAddresstrue
          incontactableByEmailCampaign:
query           descriptiontype: Caseboolean
insensitive email address        description: volunteer's permission required:to falsebe contacted by emails
       schema:   default: true
        typenextOfKin:
string         - nametype: mobilePhonestring
          indescription: query>-
          description: Will benotes convertedgenerally toabout ISOwho formatto beforecontact ashould querythere takesbe placea reason to do
       required: false    so in an emergency situation
  schema:      volunteerEmploymentStatus:
      type: string    type: string
 responses:         '200'enum:
          description: successful operation- Unemployed
         content:   - Student
        application/json:    - EmployedPartTime
         schema:   - EmployedFullTime
            type:- objectRetired
        '422'weightKilos:
          descriptiontype: renderednumber
if appointment could not be found     format: double
security:         - basicAuthexample: []123.45
   /cancelAppointment:     postheightMeters:
      tags:    type: number
   - recruit       summaryformat: Allowsdouble
for canceling a given appointment       parametersexample: 2.12
       - namevegetarian: recruitmentAppointmentId
          intype: queryboolean
          description: IDnull fromindicates sourceunknown
system           requiredsurgicallySterile:
true           schematype: boolean
          default: false
type: number       contraceptionType:
     format: int64    type: string
 responses:         '200'example: Abstinence
          description: successfulshould operationmatch a type configured in the volunteer configure component
  content:      numberOfChildren:
       application/json:   type: integer
          schemadescription: value should only be present for females
          typeminimum: 0
object          '422'maximum: 20
         descriptionmenstruationStartAge:
rendered if appointment could not be found    type: integer
 security:         -description: basicAuth:value []should components:only be present securitySchemes:for females
   basicAuth:       typeminimum: http8
      scheme: basic   schemasmaximum:   50
 VolunteerAnswer:       type: object
   menstruationEndAge:
  properties:        type: question:integer
          typedescription: stringvalue should only be present for females
    example: Favorite web application?   minimum: 10
       description: Verbatim custom volunteermaximum: question100
        answerlastPeriodStartDate:
          type: string
          descriptionexample: Answer format must match that defined by the custom question
    Volunteer:
      type: object'2024-05-27'
          description: In form of yyyy-MM-dd; value should only be present for females
        propertiesregularPeriodIntervalDays:
        externalId  type: integer
         type description: stringvalue should only be present for females
     example: '987123'    minimum: 0
     description: Unique identifier in originating recruitmentmaximum: system100
        titleregularPeriodDurationDays:
          type: stringinteger
          exampledescription: Mrvalue should only be present for females
  firstName:           typeminimum: string0
          examplemaximum: Joseph100
        middleNamecurrentlyPregnant:
          type: stringboolean
          description: >-value should only be present for females
      can be an initial, ifdefault: nofalse
value is provided a '-' will be stored withcurrentlyBreastFeeding:
          type: boolean
the volunteer reocord         lastNamedescription: value should only be present for   females
 type: string           exampledefault: Padresfalse
        genderMalechildBearingPotential:
          type: boolean
        ethnicHispanic:  description: value should only be present    type: booleanfor females
          descriptiondefault: nullfalse
indicates unknown         otherRaceallergies:
          type: stringboolean
          description: additionalnull race details if race type doesn't matchindicates unknown
           dateOfBirthemailAddress:
          type: string
          example: '1980-05-27'something@domain.com
          description: ISO>-
DOB in form of yyyy-MM-dd        must nameSuffix:be unique; strictly validated using Apache Commons Email
   type: string        Validator framework
 description: 'jr, II'         nationalitycontactSource:
          type: string
        preferredLanguage:           typedescription: string>-
        address:    describes how a volunteer contact occurred; should type:match stringa   source
     city:       configured in the volunteer type:configure stringcomponent
        regiongeneralPractitioner:
          type: string
          description: >-volunteer's physician
        generalPractitionerPhoneNumber:
  should match regions configured in the volunteer configuration type: string
          component; ie state / provincedescription: volunteer's physician phone number
        countrygeneralPractitionerAddress:
          type: string
          postalCodedescription: volunteer's physician address
        typesiteId:
 string         homePhonetype: integer
          typeformat: stringinteger
          descriptionexample: >-1
          description: >-
tightly validated based on the general settings configured; should    the id of the site that the volunteer should be as close to ISO format as possibleassociated with; leadingif
country code.           not  https://github.com/google/libphonenumber is used for underlyingprovided, use siteName
        paymentStrategy:
      validation      type: string
 workPhone:           typeenum:
 string           description: see homePhone- IBAN
       mobilePhone:       - ABA
  type: string         example: IBAN
description: 'same rules apply as homePhone, but must beibanAccount: unique
in database'         phoneNotestype: string
          typeexample: stringES9121000418450200051332
          description: canUsed beif arbitraryIBAN notesis tochosen guideas recruitersPayment aboutStrategy. makingValidated phoneusing callsiban4j.org
        contactableByPhoneibanBank:
          type: booleanstring
          descriptionexample: volunteer's permission to be contacted by phone
          default: true CAIXESBB666
          description: Used if IBAN is chosen as Payment Strategy. Validated using iban4j.org
        contactableBySmsabaAccount:
          type: booleanstring
          descriptionexample: volunteer's123456789
permission to be contacted by SMS     description: Used if ABA is chosen default:as truePayment Strategy. Validated using ABANumberCheckDigit library.
   contactableByEmailCampaign:     abaBank: 
    type: boolean     type: string
    description: volunteer's permission to be contacted byexample: emails021000021
          defaultdescription: trueUsed if ABA is chosen as Payment Strategy. Validated nextOfKin:using ABANumberCheckDigit library.
        typepreviousStudyParticipation:
 string         type: boolean
description: >-   VolunteerSubstanceUse:
      type: object
 notes generally about who to contactproperties:
should there be a reason to do  substanceUseCategory:
          sotype: instring
an emergency situation        example: volunteerEmploymentStatus:Alcohol
          typeenum:
  string          - enum:Alcohol
            - UnemployedCaffeine
            - StudentTobacco
            - EmployedPartTime Drugs
        name:
         - EmployedFullTimetype: string
          description: >-
Retired         weightKilos:   must be associated with the relevant category defined type:in the
number           format: doublevolunteer configure component
        exampleuseFrequency:
123.45          heightMeterstype: string
          typedescription: provides numbercontext to the useConsumption
       format: double  default: Week
       example: 2.12  enum:
      vegetarian:      - Day
   type: boolean        - Week
 description: null indicates unknown        - surgicallySterile:Month
          type: boolean - Year
        defaultuseConsumption:
 false         contraceptionTypetype: string
          typedescription: string >-
         example: Abstinence  the amount of the substance consumed in the defined description:frequency;
should match a type configured in the volunteer configure component   should be a number
  numberOfChildren:        default: '5'
 type: integer      consumptionUnit:
    description: value should only be present fortype: femalesstring
          minimumdescription: 0>-
          maximum: 20 must be associated with the relevant category / menstruationStartAge:name defined in the
       type: integer    volunteer configure component
    description: value should only be present for femalesdefault: Glass/Bottle (.5L)
        minimumsubstanceUseStatus:
8           maximumtype: 50string
        menstruationEndAge:  enum:
        type: integer   - Social
      description: value should only be present for- femalesRegular
          minimum: 10 - Previous
        maximumstartDate:
 100         lastPeriodStartDatetype: string
          typedescription: string>-
          description: In form of yyyy-MM-dd; valuefor shouldpartial onlydates, besimply presentomit forthe femalesfields 2009 would be
     regularPeriodIntervalDays:       2009, Jan of 2008 type:would integerbe 2008-01, Feb 12 2007 would be 2007-02-12
   description: value should only be present forendDate:
females           minimumtype: 0string
          maximumdescription: 100see startDate
        regularPeriodDurationDayslastConsumed:
          type: integerstring
          description: see startDate
  value should only be present for femalessubstanceNotes:
          minimumtype: 0string
          maximumdescription: general 100notes about the substance use
    currentlyPregnantRecruitmentAppointment:
      type: object
      typeproperties:
 boolean       id:
    description: value should only be present fortype: femalesinteger
          defaultformat: falseinteger
        currentlyBreastFeedingappointmentType:
          type: booleanstring
          descriptionexample: valueScreening
should only be present for females     description: configured with study site details
default: false         childBearingPotentialappointmentNumber:
          type: booleanstring
          descriptionexample: A0001
  value should only be present for femalesestimatedAppointmentDurationMinutes:
          defaulttype: integer
 false         allergiesformat: int32
          type: booleanexample: 60
        appointmentNotes:
       description:  null indicatestype: unknownstring
        emailAddressappointmentTime:
          type: string
          description: >-ISO date time in UTC
        mustcohort:
be unique; strictly validated using Apache Commons Email   $ref: '#/components/schemas/Cohort'
        recruitmentAppointmentStatus:
Validator framework         contactSourcetype: string
          typeenum:
string           description: >- Unassigned
            - describesAssigned
    how a volunteer contact occurred; should match a source- CheckedIn
           configured in- theFailed
volunteer configure component         generalPractitioner: - Success
        typedateCreated:
string          type: description:string
volunteer's physician         generalPractitionerPhoneNumberformat: date-time
         typelastUpdated:
string           descriptiontype: volunteer'sstring
physician phone number         generalPractitionerAddressformat:  date-time
        typestudyName: string
          descriptiontype: volunteer'sstring
physician address         siteNameexample: ABC123
         typestudyId: string
          exampletype: Baseinteger
Site           descriptionexample: >-113
        studyState:
   the name of the site that the volunteertype: shouldstring
be associated with;        enum:
    if not provided, use siteId    - ACTIVE
   siteId:         - ARCHIVED
 type: integer          - format:DESIGN
int64           example: -1 LOCKED
         descriptionepochs:
>-          type: array
 the id of the site that the volunteer should beitems:
associated with; if          $ref: '#/components/schemas/EpochShort'
 not provided, use siteName    
    volunteerAnswersCohort:
   
      type: object
 array     properties:
     example:   disabled:
         - questiontype: Favoriteboolean
web application?         default: false
    answer: Gmail   requireVolunteerRecruitment:
         - questiontype: Favoriteboolean
 number?         default: false
    answer: '123'   name:
         - questiontype: Favoritestring
decimal?          example: Cohort 1
  answer: '123.4'     description:
       - question: Favorite date?type: string
        subjectNumberAction:
    answer: '1969-07-20'     type: string
    description: >-     enum:
       array of simple objects with verbatim- ClinSparkSCREENING
questions and           - LEAD_IN
corresponding answers           items:- RANDOMIZATION
           $ref: '#/components/schemas/VolunteerAnswer' - APPOINTMENT
        volunteerRacesdataLocked:
          type: arrayboolean
          exampledescription: >-
           - Americanis Indiandata orassociated Alaskawith Nativethe cohort locked for further data
     description: Must match race names defined in ClinSparkcollection?
          itemsdefault: false
        recruitmentActive:
   type: string      type: boolean
 volunteerSubstanceUse:         description: is type: array
 the cohort active for recruitment
        examplerecruitmentMaleGoal:
          type: number
   - substanceUseCategory: Alcohol     format: int32
        namerecruitmentFemaleGoal:
Beer          type: number
   useFrequency:  Week     format: int32
        useConsumptionrecruitmentGoal:
'5'          type: number
      consumptionUnit: Glass/Bottle (.5L)  format: int32
    VolunteerSearchResult:
      substanceUseStatustype: object
Social      properties:
        startDateeligible:
'2001'          type: boolean
   lastConsumed: '2021-07-21'      description: true if the volunteer matches criteria of the substanceNotes:volunteer Enjoyssearch
heavy IPAs         default: false
description: >-       name:
     array of simple objects with verbatimtype: ClinSparkstring
questions and         description: the name of correspondingthe answersadvanced search
         itemsstudy:
 
          $ref: '#/components/schemas/VolunteerSubstanceUseStudy'
    VolunteerSubstanceUse:    site:
  type: object       properties:$ref: '#/components/schemas/Site'
        substanceUseCategorycohort:
          type: string$ref: '#/components/schemas/Cohort'
    Site:
      exampletype: Alcohol
  object
       enumproperties:
        id:
   - Alcohol      type: integer
     - Caffeine    format: integer
       - Tobaccoarchived:
          type: boolean
- Drugs         namedescription: is site archived?
       type:  string default: false
        descriptionname:
>-          type: string
 must be associated with the relevant category defined in theexample: Grafton
        volunteerRegionLabel:
  volunteer configure component      type: string
 useFrequency:           typeexample: stringState
          description: allows for providescustomizing contexta toregion the(ie useConsumptionState, Province, etc)
        defaultvolunteerEnrollmentConfirmationStatement: Week
          enumtype: string
          description: -statement Daymade during point of enrollment when staff is present
    - Week     heightUnits:
       - Month  type: string
         - Yearenum:
        useConsumption:    - Meters
     type: string      - Centimeters
   description: >-        - Inches
   the amount of the substance consumedweightUnits:
in the defined frequency;       type: string
    should be a number   enum:
       default: '5'    - Kilo
   consumptionUnit:         - Pound
type: string       address:
   description: >-      type: string
     must be associated with the relevantdescription: categorystreet /address
name defined in the     city:
       volunteer configure component type: string
        defaultstateProvince:
Glass/Bottle (.5L)         substanceUseStatustype: string
         typepostalCode:
string           enumtype: string
        country:
  - Social       type: string
     - Regular  phoneNumber:
          -type: Previousstring
        startDatefaxNumber:
          type: string
        timeZoneId:
 description: >-        type: string
   yyyy-MM-dd; for partial dates, simply omitinvestigatorId:
the fields 2009 would be      type: string
     2009, Jan of 2008investigatorName:
would be 2008-01, Feb 12 2007 would be 2007-02-12  type: string
     endDateStudy:
      type: object
  type:  string  properties:
        descriptionid:
see startDate         lastConsumedtype: integer
          typeformat: stringinteger
          descriptionstudyState:
see startDate         substanceNotestype: string
          type: stringenum:
            - DESIGN
    description: general notes about the substance use  - ACTIVE
 RecruitmentAppointment:       type: object   - LOCKED
  properties:         id: - ARCHIVED
        typename:
integer           formattype: int64string
        appointmentTypedescription:
          type: string
          exampleprotocolName:
Screening           descriptiontype: configuredstring
with study site details         appointmentNumberepochs:
          type: stringarray
          exampleitems:
   A0001         estimatedAppointmentDurationMinutes$ref: '#/components/schemas/Epoch'
    Epoch:
      type: integerobject
      properties:
        formatdisabled:
 int32         appointmentNotestype: boolean
          typedefault: stringfalse
        appointmentTimename:
          type: string
          descriptionexample: ISO date time in UTC Treatment
        description:
          cohorttype: string
         $ref: '#/components/schemas/Cohort' example: Treatment
        recruitmentAppointmentStatuscohorts:
          type: stringarray
          enumitems:
            - Unassigned$ref: '#/components/schemas/Cohort'
    EpochShort:
      type: -object
Assigned      properties:
      - CheckedIn disabled:
          type: -boolean
Failed          default:  false
- Success         dateCreatedname:
          type: string
          formatexample: date-timeTreatment
        lastUpdateddescription:
          type: string
          formatexample: date-timeTreatment
    CohortStudySite:
      type: object
      properties:
        disabledid:
          type: booleaninteger
          defaultformat: falseinteger
        requireVolunteerRecruitmentunassignedAppointmentCount:
          type: booleannumber
          defaultformat: falseint32
        nameappointmentTypes:
          type: stringarray
          example: Cohort
1         description:   - Screening
      type: string     - OPV
  subjectNumberAction:         items:
 type: string           enumtype: string
        locationOid:
  - SCREENING       type:  string
   - LEAD_IN      example: '1'
     - RANDOMIZATION  investigatorId:
          -type: APPOINTMENTstring
        dataLockedinvestigatorName:
          type: string
 boolean       appointmentsRequireRecruitmentVolunteer:
     description: >-    type: boolean
       is dataappointmentsRequireRecruitmentVolunteerInCohort:
associated with the cohort locked for further data   type: boolean
        collection?recruitmentDescription:
          defaulttype: falsestring
        recruitmentActivedefaultAppointmentDurationMinutes:
          type: booleannumber
          descriptionformat: is the cohort active for recruitmentint32
        recruitmentMaleGoal:
          type: number
          format: int32
        recruitmentFemaleGoal:
          type: number
          format: int32
        recruitmentGoalsite:
          type: number$ref: '#/components/schemas/Site'
        study:
          format: int32$ref: '#/components/schemas/Study'