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:
          contenttype: string
          application/jsonexample: Favorite web application?
          schemadescription:
  Verbatim custom volunteer question
        $refanswer: '#/components/schemas/Volunteer'
          descriptiontype: JSONstring
volunteer to add        description: required:Answer trueformat must match that defined by the responses:custom question
    Volunteer:
  '200':    type: object
     description: 'Successproperties: OK
message.'         '401'id:
          descriptiontype: 'Unauthorized:integer
Must add Basic Authentication headers'      format: integer
 '422':       externalId:
   description: >-      type: string
     Invalid request: There are input validation errors; look at the JSONexample: '987123'
          description: Unique identifier in originating recruitment responsesystem
for details.       securitytitle:
  
     - basicAuth: []   /findActiveStudySitestype: string
   get:       tagsexample: Mr
        firstName:
- recruit       summary: Finds studytype: sitesstring
that are actively recruiting       parametersexample: Joseph
       - namemiddleName: studyName
          intype: querystring
          description: >-
            can Casebe insensitivean studyinitial, nameif usedno tovalue matchis studyprovided sitesa with'-' thewill be stored with
         corresponding name  the volunteer reocord
      required: false   example: Peter
      schema:  lastName:
          type: string
         - nameexample: Padres
 siteId       genderMale:
   in: query      type: boolean
   description: >-    ethnicHispanic:
        ID of atype: givenboolean
site; only study sites with the corresponding site   description: null indicates unknown
      will be returnedotherRace:
          requiredtype: falsestring
          schemadescription: additional race details if race type doesn't match
      type: number   example: Asian
        formatdateOfBirth:
int64         - nametype: siteNamestring
          inexample: query'1980-05-27'
          description: >-ISO DOB in form of yyyy-MM-dd
       Case insensitivenameSuffix:
site name used to match study sites with the  type: string
         corresponding namedescription: jr, II
        required: false example: Jr
        schemanationality:
 
          type: string
         - nameexample: locationOidBelgian
          inpreferredLanguage: query
          descriptiontype: >-string
            Case sensitive location OID used to match study sites with the
 example: English
        address:
          correspondingtype: OIDstring
          requiredexample: false123 Yellobrick Lane
        schemacity:
 
          type: string
          responsesexample: Chicago
        '200'region:
          descriptiontype: successful operationstring
          contentdescription: >-
           application/json: should match regions configured in the volunteer configuration
      schema:      component; ie state / province
      type: array   example: Chicago
        country:
   items:       type: string
          $refexample: '#/components/schemas/StudySite'US
        '401'postalCode:
          descriptiontype: 'Unauthorized: Muststring
add Basic Authentication headers'       securityexample: 60657
       - basicAuthhomePhone:
  []   /findUnassignedAppointments:     gettype:  string
    tags:      description: >-
 - recruit       summary: Finds appointments fortightly thevalidated givenbased studyon sitethe general settings configured; should
  parameters:         - name:be studySiteIdas close to ISO format as possible with leading country code.
in: query           description: ID of a given study sitehttps://github.com/google/libphonenumber is used for underlying
            required: truevalidation
          schemaexample: +1312 554 1218
         typeworkPhone:
number          type: string
 format: int64        description: -see name:homePhone
cohortName           inexample: query+1312 554 1218
        descriptionmobilePhone:
>-          type: string
 Case insensitive cohort name used for a wild card search;description: onlysame rules apply as homePhone, but must be unique in database
  appointments that have an assigned cohort matching will beexample: returned+1312 554 1218
        requiredphoneNotes:
false           schematype: string
           typedescription: stringcan be arbitrary notes to guide recruiters about making - name: appointmentTypephone calls
          inexample: query
        contactableByPhone:
 description: >-        type: boolean
   Case insensitive appointment typed used for a wild card search; only
   description: volunteer's permission to be contacted by phone
        appointments that havedefault: antrue
apointment type matching will be returned   contactableBySms:
       required: false  type: boolean
       schema:   description: volunteer's permission to be contacted by SMS
  type: string       responsesdefault: true
        '200'contactableByEmailCampaign:
          descriptiontype: successful operationboolean
          contentdescription: volunteer's permission to be contacted by emails
     application/json:     default: true
        schemanextOfKin:
          type: string
    type: array     description: >-
          items:  notes generally about who to contact should there be a reason to do
    $ref: '#/components/schemas/RecruitmentAppointment'       so in '401':an emergency situation
        description: 'Unauthorized: Must add Basic Authentication headers'volunteerEmploymentStatus:
          securitytype:   string
     - basicAuth: []   /volunteerStudySearchenum:
    get:       tags: - Unemployed
      - recruit     - Student
summary: >-         Finds matching studies- forEmployedPartTime
the found volunteer using the advanced       - EmployedFullTime
volunteer search. The advanced searches must be not be archived and must - Retired
      have a studyweightKilos:
associated while actively recruiting. If the advanced    type: number
   search also specifies a site, that site informat: questiondouble
must match the        example: volunteer123.45
The boolean eligible property in the response array indicatesheightMeters:
        whether or nottype: anumber
study match has occurred.       parametersformat: double
       - name: volunteerId example: 2.12
        invegetarian:
 query         type: boolean
description: primary key of the volunteer     description: null indicates unknown
  required: false     surgicallySterile:
     schema:     type: boolean
      type: integer   default: false
        formatcontraceptionType:
int64         - nametype: externalIdstring
          inexample: queryAbstinence
          description: IDshould frommatch sourcea systemtype configured in the volunteer configure component
    required: false   numberOfChildren:
       schema:   type: integer
        type: string description: value should only be present for  -females
name: emailAddress           inminimum: query0
          descriptionmaximum: Case20
insensitive email address      menstruationStartAge:
    required: false     type: integer
    schema:      description: value should only be present for type:females
string         - nameminimum: mobilePhone8
          inmaximum: query50
         menstruationEndAge:
description: Will be converted to ISO format before a query takestype: placeinteger
          requireddescription: falsevalue should only be present for females
    schema:      minimum:    10
  type: string       responsesmaximum: 100
        '200'lastPeriodStartDate:
          descriptiontype: successful operationstring
          contentexample: '2024-05-27'
           application/jsondescription: In form of yyyy-MM-dd; value should only be present for  females
  schema:      regularPeriodIntervalDays:
          type: integer
    array      description: value should only be present for females
   items:       minimum: 0
          $refmaximum: '#/components/schemas/VolunteerSearchResult'100
        '401'regularPeriodDurationDays:
          descriptiontype: 'Unauthorized: Mustinteger
add Basic Authentication headers'       securitydescription: value should only be present for females
  - basicAuth: []   /listVolunteerAppointments:   minimum: 0
get:       tags:   maximum: 100
    - recruit   currentlyPregnant:
   summary: >-      type: boolean
 Finds appointments for the given volunteer found by one ofdescription: thevalue should only be present for females
  parameters supplied       parametersdefault: false
       - namecurrentlyBreastFeeding: volunteerId
          intype: queryboolean
          description: value should primaryonly keybe ofpresent thefor volunteerfemales
          requireddefault: false
          schemachildBearingPotential:
 
          type: integerboolean
          description: value format:should int64only be present for females
    - name: externalId    default: false
     in: query  allergies:
        description: ID from source systemtype: boolean
          requireddescription: falsenull indicates unknown
        schemaemailAddress:
 
          type: string
         - nameexample: emailAddresssomething@domain.com
          in: querydescription: >-
            must be description:unique; Casestrictly insensitivevalidated emailusing addressApache Commons Email
        required: false   Validator framework
      schema:  contactSource:
          type: string
          description: >-
  name: mobilePhone         describes how in:a queryvolunteer contact occurred; should match a source
    description: Will be converted to ISO format before aconfigured queryin takesthe placevolunteer configure component
        requiredgeneralPractitioner: false
          schematype: string
           typedescription: stringvolunteer's physician
     responses:     example: Joseph Smith
 '200':       generalPractitionerPhoneNumber:
   description: successful operation     type: string
    content:      description: volunteer's physician phone number
  application/json:        example: +1312 555  1212
  schema:      generalPractitionerAddress:
          type: string
array          description: volunteer's physician address
   items:       example: 232 Yellobrick Lane
        $refsiteName: '#/components/schemas/RecruitmentAppointment'
          '401'type: string
          descriptionexample: 'Unauthorized:Base MustSite
add Basic Authentication headers'       securitydescription: >-
         - basicAuth: [] the name /assignAppointment:of the site that the post:volunteer should be associated with;
  tags:         - recruitif not provided, use siteId
  summary: Allows for assigning a given appointmentsiteId:
to a matching volunteer       parameterstype: integer
         - nameformat: recruitmentAppointmentIdinteger
          inexample: query-1
          description: ID from source system
  >-
       required: true    the id of the site that the schema:volunteer should be associated with; if
       type: number    not provided, use siteName
     format: int64  paymentStrategy:
      - name: volunteerId    type: string
     in: query      enum:
    description: ID from the volunteer      - IBAN
   required: false          - schema:ABA
            typeexample: int64IBAN
        - nameibanAccount: externalId
          intype: querystring
          descriptionexample: ES9121000418450200051332
  ID from source system     description: Used if IBAN is chosen required:as falsePayment Strategy. Validated using iban4j.org
      schema:  ibanBank:
          type: string
         - nameexample: emailAddressCAIXESBB666
          in: query
     description: Used if IBAN is chosen as Payment Strategy. Validated using iban4j.org
    description: Case insensitive email addressabaAccount:
          requiredtype: falsestring
          schemaexample: 123456789
           typedescription: stringUsed if ABA is chosen as Payment Strategy. Validated -using name:ABANumberCheckDigit mobilePhonelibrary.
          inabaBank: query
          descriptiontype: Willstring
be converted to ISO format before a query takes place example: 021000021
        required: false description: Used if ABA is chosen as Payment Strategy. Validated schema:using ABANumberCheckDigit library.
          typepreviousStudyParticipation:
string         - nametype: appointmentNotesboolean
          involunteerAnswers:
query           requiredtype: falsearray
          schemaexample:
            - typequestion: Favorite stringweb application?
     responses:         '200':
    answer: Gmail
     description: successful operation     - question: Favorite  number?
 content:             application/jsonanswer: '123'
            - schemaquestion: Favorite decimal?
              typeanswer: object'123.4'
        '401':    - question: Favorite     description: 'Unauthorized: Must add Basic Authentication headers'date?
              answer: '4221969-07-20':
          description: rendered>-
if appointment could not be found       security:array of simple objects with verbatim ClinSpark questions and
- basicAuth: []   /cancelAppointment:     post:  corresponding answers
   tags:       items:
 - recruit       summary: Allows for canceling a given appointment$ref: '#/components/schemas/VolunteerAnswer'
        parametersvolunteerNotes:
         - nametype: recruitmentAppointmentIdarray
          inexample:
   query         - Volunteer description:travels IDoften
from source system          - required:Is trueafraid of needles
        schema:  description: Simple notes that move to a volunteer notes section
 type: number        items:
    format: int64       responsestype: string
        '200'volunteerRaces:
          descriptiontype: successfularray
operation          example:
content:            - application/json:American Indian or Alaska Native
          schemadescription: Must match race names defined in ClinSpark
          typeitems:
 object         '401':  type: string
       description: 'UnauthorizedvolunteerSubstanceUse:
Must add Basic Authentication headers'         '422':type: array
          descriptionexample:
rendered if appointment could not be found      - securitysubstanceUseCategory: Alcohol
       - basicAuth: [] servers:   - urlname: 'https://{customerId}.clinspark.com/api/v1'Beer
    variables:       customerId:   useFrequency: Week
    default: community-dev         descriptionuseConsumption: Customer ID assigned by the service provider'5'
       - url: 'https://{ngrokPrefix}.ngrok.io/clinspark/api/v1'     variablesconsumptionUnit: Glass/Bottle (.5L)
     ngrokPrefix:         defaultsubstanceUseStatus: 04f5b951df6dSocial
        description: first part of ngrok-assigned id componentsstartDate: '2001'
  securitySchemes:     basicAuth:       typelastConsumed: http
'2021-07-21'
     scheme: basic   schemas:     VolunteerAnswersubstanceNotes: Enjoys heavy  IPAs
  type: object       propertiesdescription: >-
        question:    array of simple objects with verbatim ClinSpark type:questions stringand
          example: Favorite webcorresponding application?answers
          descriptionitems:
Verbatim custom volunteer question         answer:$ref: '#/components/schemas/VolunteerSubstanceUse'
    VolunteerUpdate:
      type: object
string      properties:
    description: Answer format must matchid:
that defined by the custom question     Volunteertype: integer
     type: object       properties:format: integer
        externalId:
          type: string
          example: '987123'
          description: Unique identifier in originating recruitment system
        title:
          type: string
          example: Mr
        firstName:
          type: string
          example: Joseph
        middleName:
          type: string
          description: >-
            can be an initial, if no value is provided a '-' will be stored with
            the volunteer reocord
        lastName:
          type: string
          example: Padres
        genderMale:
          type: boolean
        ethnicHispanic:
          type: boolean
          description: null indicates unknown
        otherRace:
          type: string
          description: additional race details if race type doesn't match
        dateOfBirth:
          type: string
          example: '1980-05-27'
          description: ISO DOB in form of yyyy-MM-dd
        nameSuffix:
          type: string
          description: jr, II
        nationality:
          type: string
        preferredLanguage:
          type: string
        address:
          type: string
        city:
          type: string
        region:
          type: string
          description: >-
            should match regions configured in the volunteer configuration
            component; ie state / province
        country:
          type: string
        postalCode:
          type: string
        homePhone:
          type: string
          description: >-
            tightly validated based on the general settings configured; should
            be as close to ISO format as possible with leading country code.
            https://github.com/google/libphonenumber is used for underlying
            validation
        workPhone:
          type: string
          description: see homePhone
        mobilePhone:
          type: string
          description: same rules apply as homePhone, but must be unique in database
        phoneNotes:
          type: string
          description: can be arbitrary notes to guide recruiters about making phone calls
        contactableByPhone:
          type: boolean
          description: volunteer's permission to be contacted by phone
          default: true
        contactableBySms:
          type: boolean
          description: volunteer's permission to be contacted by SMS
          default: true
        contactableByEmailCampaign:
          type: boolean
          description: volunteer's permission to be contacted by emails
          default: true
        nextOfKin:
          type: string
          description: >-
            notes generally about who to contact should there be a reason to do
            so in an emergency situation
        volunteerEmploymentStatus:
          type: string
          enum:
            - Unemployed
            - Student
            - EmployedPartTime
            - EmployedFullTime
            - Retired
        weightKilos:
          type: number
          format: double
          example: 123.45
        heightMeters:
          type: number
          format: double
          example: 2.12
        vegetarian:
          type: boolean
          description: null indicates unknown
        surgicallySterile:
          type: boolean
          default: false
        contraceptionType:
          type: string
          example: Abstinence
          description: should match a type configured in the volunteer configure component
        numberOfChildren:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 20
        menstruationStartAge:
          type: integer
          description: value should only be present for females
          minimum: 8
          maximum: 50
        menstruationEndAge:
          type: integer
          description: value should only be present for females
          minimum: 10
          maximum: 100
        lastPeriodStartDate:
          type: string
          example: '2024-05-27'
          description: In form of yyyy-MM-dd; value should only be present for females
        regularPeriodIntervalDays:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 100
        regularPeriodDurationDays:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 100
        currentlyPregnant:
          type: boolean
          description: value should only be present for females
          default: false
        currentlyBreastFeeding:
          type: boolean
          description: value should only be present for females
          default: false
        childBearingPotential:
          type: boolean
          description: value should only be present for females
          default: false
        allergies:
          type: boolean
          description: null indicates unknown
        descriptionemailAddress:
null indicates unknown        type: emailAddress:string
          typeexample: stringsomething@domain.com
          description: >-
            must be unique; strictly validated using Apache Commons Email
            Validator framework
        contactSource:
          type: string
          description: >-
            describes how a volunteer contact occurred; should match a source
            configured in the volunteer configure component
        generalPractitioner:
          type: string
          description: volunteer's physician
        generalPractitionerPhoneNumber:
          type: string
          description: volunteer's physician phone number
        generalPractitionerAddress:
          type: string
          description: volunteer's physician address
        siteName:
          type: string
          example: Base Site
          description: >-volunteer's physician phone number
        generalPractitionerAddress:
the name of the site that the volunteer should be associatedtype: with;string
          description: volunteer's if not provided, use siteIdphysician address
        siteId:
          type: integer
          format: int64integer
          example: -1
          description: >-
            the id of the site that the volunteer should be associated with; if
            not provided, use siteName
        volunteerAnswerspaymentStrategy:
            type: string
 array           exampleenum:
              - IBAN
question: Favorite web application?           - ABA
  answer: Gmail         example: IBAN
  - question: Favorite number?   ibanAccount: 
          answertype: string
 '123'         example: ES9121000418450200051332
  - question: Favorite decimal?     description: Used if IBAN is chosen as Payment Strategy. Validated answer:using '123.4'iban4j.org
        ibanBank:
    - question: Favorite date?   type: string
          answerexample: '1969-07-20'CAIXESBB666
          description: >-Used if IBAN is chosen as Payment Strategy. Validated     array of simple objects with verbatim ClinSpark questions and
 using iban4j.org
        abaAccount:
          correspondingtype: answersstring
          itemsexample: 123456789
           $refdescription: '#/components/schemas/VolunteerAnswer'
        volunteerNotes:
 Used if ABA is chosen as Payment Strategy. Validated using ABANumberCheckDigit library.
        typeabaBank: array
          exampletype: string
          example: 021000021
- Volunteer travels often       description: Used if ABA is chosen -as IsPayment afraidStrategy. ofValidated needlesusing ABANumberCheckDigit library.
        descriptionpreviousStudyParticipation:
Simple notes that move to a volunteer notes section  type: boolean
    VolunteerSubstanceUse:
  items:    type: object
       typeproperties: string
        volunteerRacessubstanceUseCategory:
          type: arraystring
          example: Alcohol
          enum:
- American Indian or Alaska Native       - Alcohol
  description: Must match race names defined in ClinSpark   - Caffeine
      items:      - Tobacco
     type: string      - Drugs
 volunteerSubstanceUse:       name:
   type: array      type: string
   example:       description: >-
    - substanceUseCategory: Alcohol      must be associated with the relevant category defined in name:the
Beer            volunteer configure component
useFrequency: Week       useFrequency:
       useConsumption: '5'  type: string
           consumptionUnitdescription: Glass/Bottle (.5L)
  provides context to the useConsumption
           substanceUseStatusdefault: SocialWeek
            enum:
 startDate: '2001'          - Day
   lastConsumed: '2021-07-21'        - Week
     substanceNotes: Enjoys heavy IPAs    - Month
     description: >-      - Year
     array of simple objectsuseConsumption:
with verbatim ClinSpark questions and      type: string
     corresponding answers    description: >-
     items:       the amount of the substance consumed $ref: '#/components/schemas/VolunteerSubstanceUse'
 in the defined frequency;
  VolunteerSubstanceUse:       type: object  should be a number
 properties:         substanceUseCategorydefault: '5'
         typeconsumptionUnit: string
          exampletype: Alcoholstring
          enumdescription: >-
           - Alcoholmust be associated with the relevant category / name defined in  the
- Caffeine           volunteer configure -component
Tobacco          default:   - DrugsGlass/Bottle (.5L)
         namesubstanceUseStatus:
          type: string
          descriptionenum:
    >-        - Social
   must be associated with the relevant category defined in the- Regular
           volunteer configure- componentPrevious
        useFrequencystartDate:
          type: string
          description: provides>-
context to the useConsumption         yyyy-MM-dd; for default:partial Weekdates, simply omit the fields 2009 would  be
  enum:          2009, Jan of -2008 Daywould be 2008-01, Feb 12 2007 would be 2007-02-12
    - Week   endDate:
         - Monthtype: string
          description: -see YearstartDate
        useConsumptionlastConsumed:
          type: string
          description: >- see startDate
        substanceNotes:
          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
      defaultproperties: '5'
        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 study site  default: Glass/Bottle (.5L)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         lastConsumed:  - Unassigned
       type: string    - Assigned
     description: see startDate     - CheckedIn
  substanceNotes:          - type:Failed
string           description: general- notesSuccess
about the substance use     RecruitmentAppointmentdateCreated:
          type: string
   object       propertiesformat: date-time
        idlastUpdated:
          type: integerstring
          format: int64date-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
    string  properties:
        enum:
 disabled:
          type: 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:     - SCREENING
type: object       properties:    - LEAD_IN
   disabled:         - RANDOMIZATION
type: boolean           default:- falseAPPOINTMENT
        requireVolunteerRecruitmentdataLocked:
          type: boolean
          defaultdescription: >-
  false         name: is data associated with the cohort locked for further data
type: string           example:collection?
Cohort 1         descriptiondefault: false
        recruitmentActive:
type: string         subjectNumberActiontype: boolean
          typedescription: stringis the cohort active for recruitment
     enum:   recruitmentMaleGoal:
         - SCREENINGtype: number
          format: -int32
LEAD_IN        recruitmentFemaleGoal:
    - RANDOMIZATION     type: number
      - APPOINTMENT   format:   int32
  dataLocked:      recruitmentGoal:
    type: boolean     type: number
    description: >-     format: int32
    VolunteerSearchResult:
 is data associated with the cohorttype: lockedobject
for further data    properties:
        collection?eligible:
          defaulttype: falseboolean
        recruitmentActive:  description: true if the volunteer matches criteria of the type:volunteer booleansearch
          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'
         site:
format: int32         recruitmentGoal$ref: '#/components/schemas/Site'
         typecohort:
number           format: int32$ref: '#/components/schemas/Cohort'
    VolunteerSearchResultSite:
      type: object
      properties:
        eligibleid:
          type: booleaninteger
          descriptionformat: trueinteger
if the volunteer matches criteria of the volunteer searcharchived:
          defaulttype: boolean
 false         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:  example:    State
    $ref: '#/components/schemas/Cohort'     Sitedescription: allows for customizing a region (ie type: object
      properties:State, Province, etc)
        idvolunteerEnrollmentConfirmationStatement:
          type: integerstring
          formatdescription: int64statement made during point of enrollment when staff is archived:present
          typeheightUnits: boolean
          descriptiontype: is site archived?string
          defaultenum:
false         name:   -   Meters
    type: string       - Centimeters
  example: Grafton         volunteerRegionLabel:- Inches
         typeweightUnits:
string           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
          enumtype: 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
          faxNumberenum:
            type:- stringDESIGN
        timeZoneId:    - ACTIVE
     type: string      - LOCKED
 investigatorId:           type:- stringARCHIVED
        investigatorNamename:
          type: string
    Study:    description:
  type: object       propertiestype: string
        idprotocolName:
          type: integerstring
         epochs:
format: int64         studyStatetype: array
          typeitems: string
          enum:  $ref: '#/components/schemas/Epoch'
    Epoch:
    - DESIGN type: object
      properties:
   - ACTIVE    disabled:
        - LOCKED type: boolean
          -default: ARCHIVEDfalse
        name:
          type: string
          descriptionexample: Treatment
        description:
type: string         protocolNametype: string
          typeexample: 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: int64integer
        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'