Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Swagger integration
showCommonExtensionstrue
supportedSubmitMethodsget, post
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
         country example: Chicago
        country:
type: string         postalCodetype: string
         type example: 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
          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
        generalPractitionerAddress:  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: Favorite number?IBAN
        ibanAccount: 
    answer: '123'     type:   string
    - question: Favorite decimal?   example: ES9121000418450200051332
          answerdescription: '123.4'Mandatory if IBAN is chosen as Payment Strategy. Validated using iban4j.org
  - question: Favorite date?   ibanBank:
           answertype: '1969-07-20'string
          descriptionexample: >-CAIXESBB666
          description: Mandatory arrayif ofIBAN simpleis objectschosen withas verbatimPayment ClinSparkStrategy. questionsValidated andusing iban4j.org
        abaAccount:
  corresponding answers           itemstype: string
           $refexample: '#/components/schemas/VolunteerAnswer'123456789
        volunteerNotes:  description: Mandatory if ABA is chosen as Payment Strategy. type:Validated arrayusing ABANumberCheckDigit library.
        exampleabaBank: 
          type: -string
Volunteer travels often        example:    021000021
- Is afraid of needles           description: Mandatory Simpleif notesABA thatis movechosen toas aPayment volunteerStrategy. notesValidated sectionusing ABANumberCheckDigit library.
        itemspreviousStudyParticipation:
            type: stringboolean
        volunteerRacesvolunteerAnswers:
          type: array
          example:
            - Americanquestion: IndianFavorite orweb Alaska Nativeapplication?
              descriptionanswer: Gmail
Must match race names defined in ClinSpark      - question: Favorite number?
 items:             typeanswer: string'123'
        volunteerSubstanceUse:    - question: Favorite decimal?
   type: array           example:answer: '123.4'
            - substanceUseCategoryquestion: AlcoholFavorite date?
              nameanswer: Beer'1969-07-20'
          description: >-
   useFrequency: Week        array of simple objects with verbatim ClinSpark useConsumption: '5'questions and
            corresponding answers
consumptionUnit: Glass/Bottle (.5L)        items:
      substanceUseStatus: Social     $ref: '#/components/schemas/VolunteerAnswer'
        startDatevolunteerNotes:
 '2001'         type: array
    lastConsumed: '2021-07-21'     example:
         substanceNotes: Enjoys heavy IPAs- Volunteer travels often
       description: >-     - Is       array afraid of simpleneedles
objects with verbatim ClinSpark questions and     description: Simple notes that move to a volunteer correspondingnotes answerssection
          items:
            $reftype: '#/components/schemas/VolunteerSubstanceUse'string
    VolunteerUpdate:    volunteerRaces:
  type: object       propertiestype:  array
      id:    example:
      type: integer     - American Indian or Alaska Native
format: integer         externalIddescription: Must match race names defined in ClinSpark
   type: string           example: '987123'items:
            descriptiontype: Uniquestring
identifier in originating recruitment system         titlevolunteerSubstanceUse:
          type: stringarray
          example:
Mr         firstName:   - substanceUseCategory: Alcohol
     type: string        name: Beer
 example:    Joseph         middleName:useFrequency: Week
              typeuseConsumption: string'5'
           description: >-  consumptionUnit: Glass/Bottle (.5L)
        can be an initial, if no valuesubstanceUseStatus: isSocial
provided a '-' will be stored with        startDate: '2001'
   the volunteer reocord         lastNamelastConsumed: '2021-07-21'
         type: string    substanceNotes: Enjoys heavy IPAs
   example: Padres      description: >-
 genderMale:           type:array booleanof simple objects with verbatim ClinSpark questions and
 ethnicHispanic:           type:corresponding booleananswers
          descriptionitems:
 null indicates unknown         otherRace:$ref: '#/components/schemas/VolunteerSubstanceUse'
    VolunteerUpdate:
      type: object
string      properties:
    description: additional race details if race type doesn't match    id:
          type: integer
          format: integer
        dateOfBirthexternalId:
          type: string
          example: '1980-05-27987123'
          description: ISOUnique DOBidentifier in formoriginating of yyyy-MM-ddrecruitment system
        nameSuffixtitle:
          type: string
          descriptionexample: jr, IIMr
        nationalityfirstName:
          type: string
        preferredLanguage  example: Joseph
        middleName:
type: string         addresstype: string
          typedescription: string>-
        city:    can be an initial, if no value type:is stringprovided a '-' will be stored with
  region:          the type:volunteer stringreocord
          descriptionlastName:
>-          type: string
 should match regions configured in the volunteer configuration  example: Padres
        genderMale:
component; ie state / province      type: boolean
 country:       ethnicHispanic:
   type: string      type: boolean
 postalCode:         description: null type:indicates stringunknown
        homePhoneotherRace:
          type: string
          description: >-additional race details if race type     doesn't match
  tightly validated based on the general settingsdateOfBirth:
configured; should         type:   string
be as close to ISO format as possible with leading country code.example: '1980-05-27'
            https://github.com/google/libphonenumber is used for underlying
 description: ISO DOB in form of yyyy-MM-dd
        nameSuffix:
 validation         workPhonetype: string
         type description: stringjr, II
         descriptionnationality:
see homePhone         mobilePhonetype: string
         typepreferredLanguage:
string          type: description:string
same rules apply as homePhone, but must be uniqueaddress:
in database         phoneNotestype: string
         typecity:
string          type: description:string
can be arbitrary notes to guide recruiters about makingregion:
phone calls         contactableByPhonetype: string
         type description: boolean>-
          description: volunteer's permissionshould tomatch beregions contactedconfigured byin phonethe volunteer configuration
        default: true   component; ie state / province
 contactableBySms:       country:
   type: boolean      type:   string
 description: volunteer's permission to be contacted by SMSpostalCode:
          defaulttype: truestring
        contactableByEmailCampaignhomePhone:
          type: booleanstring
          description: volunteer's>-
permission to be contacted by emails       tightly validated based on default:the truegeneral settings configured; should
     nextOfKin:       be as close to type:ISO stringformat as possible with leading country code.
    description: >-       https://github.com/google/libphonenumber is used for underlying
 notes generally about who to contact should there be a reason tovalidation
do        workPhone:
    so in an emergency situation  type: string
     volunteerEmploymentStatus:     description: see homePhone
   type: string    mobilePhone:
      enum:    type: string
       - Unemployed  description: same rules apply as homePhone, but must be unique in -database
Student        phoneNotes:
    - EmployedPartTime     type: string
      - EmployedFullTime   description: can be arbitrary notes to guide recruiters about making -phone Retiredcalls
        weightKiloscontactableByPhone:
          type: numberboolean
          formatdescription: doublevolunteer's permission to be contacted by phone
     example     default: 123.45true
        heightMeterscontactableBySms:
          type: numberboolean
          format: doubledescription: volunteer's permission to be contacted by SMS
          exampledefault: 2.12true
        vegetariancontactableByEmailCampaign:
          type: boolean
          description: null indicates unknown volunteer's permission to be contacted by emails
          surgicallySteriledefault: true
         typenextOfKin:
boolean          type: default:string
 false         contraceptionTypedescription: >-
         type: string  notes generally about who to contact should there be example:a Abstinencereason to do
        description: should match a typeso configured in thean volunteeremergency configuresituation
component         numberOfChildrenvolunteerEmploymentStatus:
          type: integerstring
          descriptionenum:
value should only be present for females      - Unemployed
   minimum: 0        - Student
 maximum: 20         menstruationStartAge: - EmployedPartTime
        type: integer   - EmployedFullTime
      description: value should only be present for- femalesRetired
        weightKilos:
 minimum: 8        type: number
 maximum: 50        format: menstruationEndAge:double
          typeexample: 123.45
 integer       heightMeters:
   description:  value should only be present fortype: femalesnumber
          minimumformat: 10double
          maximumexample: 1002.12
        lastPeriodStartDatevegetarian:
          type: stringboolean
          exampledescription: '2024-05-27'
 null indicates unknown
        descriptionsurgicallySterile:
   In form of yyyy-MM-dd; value should only betype: presentboolean
for females         regularPeriodIntervalDaysdefault: false
         typecontraceptionType:
integer           descriptiontype: valuestring
should only be present for females     example: Abstinence
    minimum: 0     description: should match a type configured in the volunteer maximum:configure 100component
        regularPeriodDurationDaysnumberOfChildren:
          type: integer
          description: value should only be present for females
          minimum: 0
          maximum: 10020
        currentlyPregnantmenstruationStartAge:
          type: booleaninteger
          description: value should only be present for females
          minimum: 8
 default         maximum: false50
        currentlyBreastFeedingmenstruationEndAge:
          type: booleaninteger
          description: value should only be present for females
          minimum: 10
          defaultmaximum: false100
        childBearingPotentiallastPeriodStartDate:
          type: booleanstring
          description: value should only be present for females
          default: falseexample: '2024-05-27'
          description: In form of yyyy-MM-dd; value should only be present for females
        allergiesregularPeriodIntervalDays:
          type: booleaninteger
          description: nullvalue indicatesshould unknownonly be present for females
    emailAddress:      minimum: 0
   type:   string    maximum: 100
     example: something@domain.com   regularPeriodDurationDays:
          descriptiontype: >-integer
          description: value mustshould only be unique; strictly validated using Apache Commons Email
  present for females
          minimum: 0
          Validatormaximum: framework100
        contactSourcecurrentlyPregnant:
          type: stringboolean
          description: >-value should only be present for females
       describes how a volunteerdefault: contactfalse
occurred; should match a source    currentlyBreastFeeding:
        configured in thetype: volunteerboolean
configure component         generalPractitionerdescription: value should only be present for females
   type: string           descriptiondefault: volunteer'sfalse
physician         generalPractitionerPhoneNumberchildBearingPotential:
          type: stringboolean
          description: volunteer'svalue physicianshould phoneonly numberbe present for females
     generalPractitionerAddress     default: false
        allergies:
          type: stringboolean
          description: volunteer'snull physicianindicates addressunknown
        siteIdemailAddress:
          type: integerstring
          formatexample: integersomething@domain.com
          exampledescription: -1
  >-
            must be unique; strictly validated using Apache Commons Email
            Validator framework
       description contactSource: >-
          type: string
        the id ofdescription: the>-
site that the volunteer should be associated with; if    describes how a volunteer contact occurred; should match a notsource
provided, use siteName           configured in the volunteer configure component
        generalPractitioner:
          type: string
          description: volunteer's physician
        generalPractitionerPhoneNumber:
          type: string
          description: volunteer's physician phone number
        generalPractitionerAddress:
          type: string
          description: volunteer's physician address
        siteId:
          type: integer
          format: integer
          example: -1
          description: >-
            the id of the site that the volunteer should be associated with; if
            not provided, use siteName
        paymentStrategy:
            type: string
            enum:
              - IBAN
              - ABA
            example: IBAN
        ibanAccount: 
          type: string
          example: ES9121000418450200051332
          description: Mandatory if IBAN is chosen as Payment Strategy. Validated using iban4j.org
        ibanBank:
          type: string
          example: CAIXESBB666
          description: Mandatory if IBAN is chosen as Payment Strategy. Validated using iban4j.org
        abaAccount:
          type: string
          example: 123456789
          description: Mandatory if ABA is chosen as Payment Strategy. Validated using ABANumberCheckDigit library.
        abaBank: 
          type: string
          example: 021000021
          description: Mandatory if ABA is chosen as Payment Strategy. Validated using ABANumberCheckDigit library.
        previousStudyParticipation:
          type: boolean
    VolunteerSubstanceUse:
      type: object
      properties:
        substanceUseCategory:
          type: string
          example: Alcohol
          enum:
            - Alcohol
            - Caffeine
            - Tobacco
            - Drugs
        name:
          type: string
          description: >-
            must be associated with the relevant category defined in the
            volunteer configure component
        useFrequency:
          type: string
          description: provides context to the useConsumption
          default: Week
          enum:
            - Day
            - Week
            - Month
            - Year
        useConsumption:
          type: string
          description: >-
            the amount of the substance consumed in the defined frequency;
            should be a number
          default: '5'
        consumptionUnit:
          type: string
          description: >-
            must be associated with the relevant category / name defined in the
            volunteer configure component
          default: Glass/Bottle (.5L)
        substanceUseStatus:
          type: string
          enum:
            - Social
            - Regular
            - Previous
        startDate:
          type: string
          description: >-
            yyyy-MM-dd; for partial dates, simply omit the fields 2009 would be
            2009, Jan of 2008 would be 2008-01, Feb 12 2007 would be 2007-02-12
        endDate:
          type: string
          description: see startDate
        lastConsumed:
          type: string
          description: see startDate
        substanceNotes:
          type: string
          description: general notes about the substance use
    RecruitmentAppointment:
      type: object
      properties:
        id:
          type: integer
          format: integer
        appointmentType:
          type: string
          example: Screening
          description: configured with study site details
        appointmentNumber:
          type: string
          example: A0001
        estimatedAppointmentDurationMinutes:
          type: integer
          format: int32
          example: 60
        appointmentNotes:
          type: string
        appointmentTime:
          type: string
          description: ISO date time in UTC
        cohort:
          $ref: '#/components/schemas/Cohort'
        recruitmentAppointmentStatus:
          type: string
          enum:
            - Unassigned
            - Assigned
            - CheckedIn
            - Failed
            - Success
        dateCreated:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        studyName: 
          type: string
          example: ABC123
        studyId:
          type: integer
          example: 113
        studyState:
          type: string
          enum:
            - ACTIVE
            - ARCHIVED
            - DESIGN
            - LOCKED
        epochs:
          type: array
          items:
            $ref: '#/components/schemas/EpochShort'
        
    Cohort:
      type: object
      properties:
        disabled:
          type: boolean
          default: false
        requireVolunteerRecruitment:
          type: boolean
          default: false
        name:
          type: string
          example: Cohort 1
        description:
          type: string
        subjectNumberAction:
          type: string
          enum:
            - SCREENING
            - LEAD_IN
            - RANDOMIZATION
            - APPOINTMENT
        dataLocked:
          type: boolean
          description: >-
            is data associated with the cohort locked for further data
            collection?
          default: false
        recruitmentActive:
          type: boolean
          description: is the cohort active for recruitment
        recruitmentMaleGoal:
          type: number
          format: int32
        recruitmentFemaleGoal:
          type: number
          format: int32
        recruitmentGoal:
          type: number
          format: int32
    VolunteerSearchResult:
      type: object
      properties:
        eligible:
          type: boolean
          description: true if the volunteer matches criteria of the volunteer search
          default: false
        name:
          type: string
          description: the name of the advanced search
        study:
          $ref: '#/components/schemas/Study'
        site:
          $ref: '#/components/schemas/Site'
        cohort:
          $ref: '#/components/schemas/Cohort'
    Site:
      type: object
      properties:
        id:
          type: integer
          format: integer
        archived:
          type: boolean
          description: is site archived?
          default: false
        name:
          type: string
          example: Grafton
        volunteerRegionLabel:
          type: string
          example: State
          description: allows for customizing a region (ie State, Province, etc)
        volunteerEnrollmentConfirmationStatement:
          type: string
          description: statement made during point of enrollment when staff is present
        heightUnits:
          type: string
          enum:
            - Meters
            - Centimeters
            - Inches
        weightUnits:
          type: string
          enum:
            - Kilo
            - Pound
        address:
          type: string
          description: street address
        city:
          type: string
        stateProvince:
          type: string
        postalCode:
          type: string
        country:
          type: string
        phoneNumber:
          type: string
        faxNumber:
          type: string
        timeZoneId:
          type: string
        investigatorId:
          type: string
        investigatorName:
          type: string
    Study:
      type: object
      properties:
        id:
          type: integer
          format: integer
        studyState:
          type: string
          enum:
            - DESIGN
            - ACTIVE
            - LOCKED
            - ARCHIVED
        name:
          type: string
        description:
          type: string
        protocolName:
          type: string
        epochs:
          type: array
          items:
            $ref: '#/components/schemas/Epoch'
    Epoch:
      type: object
      properties:
        disabled:
          type: boolean
          default: false
        name:
          type: string
          example: Treatment
        description:
          type: string
          example: Treatment
        cohorts:
          type: array
          items:
            $ref: '#/components/schemas/Cohort'
    EpochShort:
      type: object
      properties:
        disabled:
          type: boolean
          default: false
        name:
          type: string
          example: Treatment
        description:
          type: string
          example: Treatment
    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'

...