...
Swagger integration | ||||
---|---|---|---|---|
| ||||
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' |
...