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:  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
        country  example: Chicago
        country:
type: string         postalCodetype: string
          typeexample: stringUS
        homePhonepostalCode:
          type: string
          descriptionexample: >-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
          descriptionexample: In form of yyyy-MM-dd; value '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
        generalPractitionerAddress:
          type: string
          description: volunteer's physician address
          example: 232 Yellobrick Lane
        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
        volunteerAnswerspaymentStrategy:
            type: arraystring
          example:  enum:
          - question: Favorite web application?- IBAN
             answer: Gmail- ABA
           - questionexample: FavoriteIBAN
number?        ibanAccount: 
     answer: '123'
        type: string
          example: ES9121000418450200051332
          description: Used if IBAN is chosen as Payment Strategy. Validated using iban4j.org
        ibanBank:
          type: string
          example: CAIXESBB666
          description: Used if IBAN is chosen as Payment Strategy. Validated using iban4j.org
        abaAccount:
          type: string
          example: 123456789
          description: Used if ABA is chosen as Payment Strategy. Validated using ABANumberCheckDigit library.
        abaBank: 
          type: string
          example: 021000021
          description: Used if ABA is chosen as Payment Strategy. Validated using ABANumberCheckDigit library.
        previousStudyParticipation:
          type: boolean
        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:
       -   questiontype: Favorite decimal? string
          example: Mr
        answerfirstName:
'123.4'          type: string
         - questionexample: Joseph
Favorite    date?    middleName:
          answertype: '1969-07-20'string
          description: >-
            array of simple objects with verbatim ClinSpark questions and
   can be an initial, if no value is provided a '-' will be stored with
            the volunteer reocord
        lastName:
          type: string
        corresponding answers example: Padres
        itemsgenderMale:
            $reftype: '#/components/schemas/VolunteerAnswer'boolean
        volunteerNotesethnicHispanic:
          type: arrayboolean
          exampledescription: null indicates unknown
        otherRace:
- Volunteer travels often       type: string
    - Is afraid of needles  description: additional race details if race type doesn't match
description: Simple notes that move to a volunteer notesdateOfBirth:
section          type: items:string
          example:  type: string'1980-05-27'
          volunteerRacesdescription: ISO DOB in form of yyyy-MM-dd
    type: array   nameSuffix:
       example:   type: string
        - American Indiandescription: orjr, AlaskaII
Native        nationality:
  description: Must match race names defined in ClinSpark type: string
        itemspreferredLanguage:
 
          type: string
        volunteerSubstanceUseaddress:
          type: arraystring
        city:
 example:         type: string
  - substanceUseCategory: Alcohol    region:
          nametype: Beerstring
          description: >-
  useFrequency: Week         should match regions configured in the useConsumption: '5'volunteer configuration
            component; ie consumptionUnit:state Glass/Bottle (.5L)province
        country:
     substanceUseStatus: Social    type: string
         startDatepostalCode:
'2001'          type: string
   lastConsumed: '2021-07-21'    homePhone:
          substanceNotestype: Enjoys heavystring
IPAs           description: >-
            arraytightly ofvalidated simplebased objectson withthe verbatimgeneral ClinSparksettings questionsconfigured; andshould
            correspondingbe answersas close to ISO format as possible with leading country  items:code.
            $refhttps: '#/components/schemas/VolunteerSubstanceUse'
    VolunteerUpdate:
 //github.com/google/libphonenumber is used for underlying
     type: object      validation
properties:         idworkPhone:
          type: integerstring
          formatdescription: integersee homePhone
        externalIdmobilePhone:
          type: string
          exampledescription: '987123'
      same rules apply as homePhone, but must be unique in database
    description: Unique identifier in originatingphoneNotes:
recruitment system         titletype: string
          typedescription: stringcan be arbitrary notes to guide recruiters about making phone calls
example: Mr         firstNamecontactableByPhone:
          type: stringboolean
          exampledescription: Josephvolunteer's permission to be contacted by phone
  middleName:           typedefault: stringtrue
          descriptioncontactableBySms:
>-          type: boolean
 can be an initial, if no value is provided adescription: '-volunteer's willpermission to be storedcontacted withby SMS
          default: the volunteertrue
reocord         lastNamecontactableByEmailCampaign:
          type: stringboolean
          exampledescription: Padresvolunteer's permission to be contacted by emails
  genderMale:           typedefault: booleantrue
        ethnicHispanicnextOfKin:
          type: booleanstring
          description: null>-
indicates unknown         otherRace:  notes generally about who to contact should there be type:a stringreason to do
        description: additional race details ifso racein typean doesn'temergency matchsituation
        dateOfBirthvolunteerEmploymentStatus:
          type: string
          exampleenum: '1980-05-27'
            - Unemployed
            - Student
 description: ISO DOB in form of yyyy-MM-dd     - EmployedPartTime
  nameSuffix:          - type:EmployedFullTime
string           description: jr,- IIRetired
        nationalityweightKilos:
          type: number
 string         preferredLanguageformat: double
         type example: string123.45
        addressheightMeters:
          type: number
 string         cityformat: double
         type example: string2.12
        regionvegetarian:
          type: stringboolean
          description: >-null indicates unknown
        surgicallySterile:
 should match regions configured in the volunteer configuration  type: boolean
         component; iedefault: statefalse
/ province         countrycontraceptionType:
          type: string
          postalCodeexample: Abstinence
          typedescription: stringshould match a type configured in the volunteer configure homePhone:component
          typenumberOfChildren:
string           descriptiontype: >-integer
          description: value tightlyshould validatedonly basedbe onpresent the general settings configured; shouldfor females
           minimum: 0
be as close to ISO format as possible with leading countrymaximum: code.20
        menstruationStartAge:
   https://github.com/google/libphonenumber is used for underlying   type: integer
        validation  description: value should only be present for workPhone:females
          typeminimum: string8
          descriptionmaximum: see homePhone50
        mobilePhonemenstruationEndAge:
          type: stringinteger
          description: samevalue rulesshould applyonly asbe homePhone,present butfor mustfemales
be unique in database       minimum: 10
phoneNotes:           typemaximum: string100
        lastPeriodStartDate:
 description:  can be arbitrary notes to guide recruiters abouttype: makingstring
phone calls         contactableByPhoneexample: '2024-05-27'
          type: boolean
      description: In form of yyyy-MM-dd; value should only be present for females
   description: volunteer's permission to be contactedregularPeriodIntervalDays:
by phone         type: integer
default: true         contactableBySmsdescription: value should only be present for females
   type: boolean      minimum: 0
   description: volunteer's permission to be contacted by SMS maximum: 100
        defaultregularPeriodDurationDays:
true          contactableByEmailCampaigntype: integer
          typedescription: booleanvalue should only be present for females
    description: volunteer's permission to be contacted byminimum: emails0
          defaultmaximum: true100
        nextOfKincurrentlyPregnant:
          type: stringboolean
          description: >-value should only be present for females
      notes generally about who todefault: contactfalse
should there be a reason to do  currentlyBreastFeeding:
          so in an emergency situationtype: boolean
          volunteerEmploymentStatusdescription: value should only be present for females
   type: string      default: false
   enum:     childBearingPotential:
       - Unemployed  type: boolean
         - Studentdescription: value should only be present for females
     - EmployedPartTime    default: false
       - EmployedFullTimeallergies:
          type: boolean
- Retired         weightKilosdescription: null indicates unknown
        typeemailAddress:
number           formattype: doublestring
          example: 123something@domain.45com
          heightMetersdescription: >-
         type: number  must be unique; strictly validated using Apache Commons Email
format: double           example: 2.12Validator framework
        vegetariancontactSource:
          type: booleanstring
          description: >-
null  indicates unknown         surgicallySterile:describes how a volunteer contact occurred; should match a source
  type:   boolean       configured in the volunteer default:configure falsecomponent
        contraceptionTypegeneralPractitioner:
          type: string
          exampledescription: Abstinencevolunteer's physician
         descriptiongeneralPractitionerPhoneNumber: should
match a type configured in the volunteer configure component  type: string
     numberOfChildren:     description: volunteer's physician phone number
 type: integer      generalPractitionerAddress:
    description: value should only be present fortype: femalesstring
          minimumdescription: 0volunteer's physician address
        maximumsiteId:
 20         menstruationStartAgetype: integer
          typeformat: integer
          descriptionexample: value-1
should only be present for females     description: >-
    minimum: 8       the id of the maximum:site 50that the volunteer should be associated with; if
 menstruationEndAge:           type:not integerprovided, use siteName
        descriptionpaymentStrategy:
value should only be present for females       type: string
  minimum: 10         enum:
 maximum: 100         lastPeriodStartDate:   - IBAN
      type: string       - ABA
  description: In form of yyyy-MM-dd; value should only be present forexample: femalesIBAN
        regularPeriodIntervalDaysibanAccount: 
          type: integerstring
          descriptionexample: valueES9121000418450200051332
should only be present for females           minimumdescription: 0Used if IBAN is chosen as Payment Strategy. Validated using iban4j.org
maximum: 100         regularPeriodDurationDaysibanBank:
          type: integerstring
          descriptionexample: value should onlyCAIXESBB666
be present for females           minimumdescription: 0Used if IBAN is chosen as Payment Strategy. Validated using  maximum: 100iban4j.org
         currentlyPregnantabaAccount:
          type: booleanstring
          descriptionexample: value should only be present for females123456789
          defaultdescription: falseUsed if ABA is chosen as Payment Strategy. Validated currentlyBreastFeeding:using ABANumberCheckDigit library.
        typeabaBank: boolean
          descriptiontype: value should only be present for females string
          example: 021000021
          defaultdescription: falseUsed if ABA is chosen as Payment Strategy. Validated childBearingPotential:using ABANumberCheckDigit library.
        typepreviousStudyParticipation:
  boolean        type: boolean
 description: value should onlyVolunteerSubstanceUse:
be present for females   type: object
      defaultproperties: false
        allergiessubstanceUseCategory:
          type: booleanstring
          descriptionexample: nullAlcohol
indicates unknown         emailAddressenum:
          type: string - Alcohol
        description: >-   - Caffeine
        must be unique; strictly validated- usingTobacco
Apache Commons Email          -  Drugs
Validator framework         contactSourcename:
          type: string
          description: >-
  >-
         describes how a volunteermust contactbe occurred;associated shouldwith matchthe arelevant sourcecategory defined in the
         configured in the volunteer configure component
        generalPractitioneruseFrequency:
          type: string
          description: volunteer'sprovides physiciancontext to the useConsumption
     generalPractitionerPhoneNumber:           typedefault: stringWeek
          descriptionenum:
volunteer's physician phone number         generalPractitionerAddress:- Day
         type: string  - Week
       description: volunteer's physician address  - Month
     siteId:       -   Year
type: integer           formatuseConsumption:
integer           exampletype: -1string
          description: >-
            the idamount of the substance siteconsumed thatin the volunteer should be associated withdefined frequency;
if             not provided, use siteName
    VolunteerSubstanceUse:
   should be a number
  type: object       propertiesdefault: '5'
        substanceUseCategoryconsumptionUnit:
          type: string
          exampledescription: Alcohol>-
          enum:  must be associated with the relevant category / name defined in -the
Alcohol            volunteer -configure Caffeinecomponent
          default:  - TobaccoGlass/Bottle (.5L)
        substanceUseStatus:
    - Drugs     type: string
  name:        enum:
  type: string         - Social
description: >-           - Regular
must be associated with the relevant category defined in the   - Previous
        volunteerstartDate:
configure component         useFrequencytype: string
          typedescription: string>-
          description: provides context to the useConsumption
       yyyy-MM-dd; for partial dates, simply omit the fields 2009 would be
   default: Week        2009, Jan of enum:2008   would be 2008-01, Feb 12 2007 would be 2007-02-12
 - Day      endDate:
      - Week   type: string
        - Month description: see startDate
        lastConsumed:
- Year         useConsumptiontype: string
         type description: stringsee startDate
         descriptionsubstanceNotes:
>-          type: string
 the amount of the substance consumed in the defined frequency;description: general notes about the substance use
    RecruitmentAppointment:
 should be a number  type: object
       default: '5'properties:
        consumptionUnitid:
          type: stringinteger
          descriptionformat: >-integer
        appointmentType:
   must be associated with the relevant category /type: namestring
defined in the        example: Screening
   volunteer configure component     description: configured with    default: Glass/Bottle (.5L)study site details
        substanceUseStatusappointmentNumber:
          type: string
          enumexample: A0001
        estimatedAppointmentDurationMinutes:
      - Social   type: integer
        - Regular format: int32
          -example: Previous60
        startDateappointmentNotes:
          type: string
          descriptionappointmentTime:
>-          type: string
 yyyy-MM-dd; for partial dates, simply omit the fields 2009 woulddescription: beISO date time in UTC
        2009,cohort:
Jan of 2008 would be 2008-01, Feb 12 2007 would be 2007-02-12$ref: '#/components/schemas/Cohort'
        endDaterecruitmentAppointmentStatus:
          type: string
          descriptionenum:
see     startDate       - Unassigned
lastConsumed:           type: string- Assigned
         description: see startDate - CheckedIn
      substanceNotes:      - Failed
   type: string        - Success
 description: general notes about the substance use dateCreated:
   RecruitmentAppointment:       type: string
   object       propertiesformat: date-time
       id lastUpdated:
          type: integerstring
          format: integerdate-time
        appointmentTypestudyName: 
          type: string
          example: Screening ABC123
        studyId:
       description:  configured withtype: studyinteger
site details         appointmentNumberexample: 113
        studyState:
type: string         type: string
example: A0001         estimatedAppointmentDurationMinutesenum:
          type: integer - ACTIVE
        format: int32   - ARCHIVED
    appointmentNotes:        - DESIGN
 type: string         appointmentTime: - LOCKED
        typeepochs:
string           descriptiontype: ISOarray
date time in UTC       items:
 cohort:           $ref: '#/components/schemas/CohortEpochShort'
        
recruitmentAppointmentStatus:
    Cohort:
      type: object
      properties:
         typedisabled:
string           enumtype: boolean
          default: - Unassignedfalse
        requireVolunteerRecruitment:
   - Assigned      type: boolean
     - CheckedIn    default: false
       - Failedname:
          type: string
- Success         dateCreatedexample: Cohort 1
        typedescription:
string           formattype: date-timestring
        lastUpdatedsubjectNumberAction:
          type: string
          formatenum:
date-time     Cohort:       type:- objectSCREENING
      properties:      - LEAD_IN
 disabled:           - type:RANDOMIZATION
 boolean           default:- falseAPPOINTMENT
        requireVolunteerRecruitmentdataLocked:
          type: boolean
          defaultdescription: false>-
        name:    is data associated with the cohort locked  type: stringfor further data
            example:collection?
Cohort 1         descriptiondefault: false
        recruitmentActive:
type: string         subjectNumberActiontype: boolean
          description: is the type:cohort stringactive for recruitment
        enumrecruitmentMaleGoal:
          type: number
 - SCREENING        format: int32
   - LEAD_IN    recruitmentFemaleGoal:
        - RANDOMIZATION type: number
          -format: APPOINTMENTint32
        dataLockedrecruitmentGoal:
          type: booleannumber
          descriptionformat: >-int32
    VolunteerSearchResult:
      type: isobject
data associated with the cohort locked forproperties:
further data       eligible:
     collection?     type: boolean
    default: false         recruitmentActivedescription: true if the volunteer matches criteria of the volunteer  type:search
boolean           descriptiondefault: isfalse
the cohort active for recruitment    name:
    recruitmentMaleGoal:      type: string
   type: number      description: the name of the format:advanced int32search
        recruitmentFemaleGoalstudy:
          type$ref: number
 '#/components/schemas/Study'
        formatsite:
int32          recruitmentGoal$ref: '#/components/schemas/Site'
         typecohort:
number           format$ref: int32'#/components/schemas/Cohort'
    VolunteerSearchResultSite:
      type: object
      properties:
        eligibleid:
          type: booleaninteger
          descriptionformat: trueinteger
if the volunteer matches criteria of the volunteer searcharchived:
          defaulttype: falseboolean
          namedescription: is site archived?
       type: string  default: false
       description: the name:
of the advanced search       type:  study:string
          $refexample: '#/components/schemas/Study'Grafton
        sitevolunteerRegionLabel:
          $reftype: '#/components/schemas/Site'string
        cohort:
          $ref: '#/components/schemas/Cohort'
  example: State
   Site:       typedescription: allows objectfor customizing a region (ie State, Province, properties:etc)
        idvolunteerEnrollmentConfirmationStatement:
          type: integerstring
          formatdescription: integerstatement made during point of enrollment when staff is archived:present
          typeheightUnits:
boolean           descriptiontype: isstring
site archived?           defaultenum:
false         name:   - Meters
      type: string     - Centimeters
    example: Grafton       - Inches
volunteerRegionLabel:           type: stringweightUnits:
          exampletype: Statestring
          descriptionenum:
allows for customizing a region (ie State, Province, etc)    - Kilo
   volunteerEnrollmentConfirmationStatement:         - Pound
type: string       address:
   description: statement made during point of enrollment whentype: staffstring
is present         heightUnitsdescription: street address
        typecity:
string          type: enum:string
        stateProvince:
   - Meters      type: string
     - Centimeters  postalCode:
          -type: Inchesstring
        weightUnitscountry:
          type: string
        phoneNumber:
 enum:         type: string
     - Kilo  faxNumber:
          -type: Poundstring
        addresstimeZoneId:
          type: string
          descriptioninvestigatorId:
street address         citytype: string
        investigatorName:
type: string         stateProvincetype: string
    Study:
      type: stringobject
        postalCodeproperties:
        id:
 type: string        type: country:integer
          typeformat: stringinteger
        phoneNumberstudyState:
          type: string
        faxNumber  enum:
           type: string- DESIGN
       timeZoneId:     - ACTIVE
    type: string       - LOCKED
investigatorId:            type:- stringARCHIVED
        investigatorNamename:
          type: string
    Study:    description:
  type: object       propertiestype: string
        idprotocolName:
          type: integerstring
          formatepochs:
integer          studyStatetype: array
          typeitems:
string            enum$ref: '#/components/schemas/Epoch'
    Epoch:
      -type: DESIGNobject
      properties:
     - ACTIVE  disabled:
          -type: LOCKEDboolean
          default: false
- ARCHIVED
        name:
          type: string
          descriptionexample: Treatment
        description:
type: string         protocolNametype: string
         type example: stringTreatment
        epochscohorts:
          type: array
          items:
            $ref: '#/components/schemas/EpochCohort'
    EpochEpochShort:
      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'