...
| 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
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
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
generalPractitionerPhoneNumber:
type: string
description: volunteer's physician phone number
generalPractitionerAddress:
type: string
description: volunteer's physician address
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
volunteerAnswers:
type: array
example:
- question: Favorite web application?
answer: Gmail
- question: Favorite number?
answer: '123'
- question: Favorite decimal?
answer: '123.4'
- question: Favorite date?
answer: '1969-07-20'
description: >-
array of simple objects with verbatim ClinSpark questions and
corresponding answers
items:
$ref: '#/components/schemas/VolunteerAnswer'
volunteerNotes:
type: array
example:
- Volunteer travels often
- Is afraid of needles
description: Simple notes that move to a volunteer notes section
items:
type: string
volunteerRaces:
type: array
example:
- American Indian or Alaska Native
description: Must match race names defined in ClinSpark
items:
type: string
volunteerSubstanceUse:
type: array
example:
- substanceUseCategory: Alcohol
name: Beer
useFrequency: Week
useConsumption: '5'
consumptionUnit: Glass/Bottle (.5L)
substanceUseStatus: Social
startDate: '2001'
lastConsumed: '2021-07-21'
substanceNotes: Enjoys heavy IPAs
description: >-
array of simple objects with verbatim ClinSpark questions and
corresponding answers
items:
$ref: '#/components/schemas/VolunteerSubstanceUse'
VolunteerUpdate:
type: object
properties:
id:
type: integer
format: integer
externalId:
type: string
example: '987123'
description: Unique identifier in originating recruitment system
title:
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
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
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
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
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
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'
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'
|
| 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
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
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
generalPractitionerPhoneNumber:
type: string
description: volunteer's physician phone number
generalPractitionerAddress:
type: string
description: volunteer's physician address
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
volunteerAnswers:
type: array
example:
- question: Favorite web application?
answer: Gmail
- question: Favorite number?
answer: '123'
- question: Favorite decimal?
answer: '123.4'
- question: Favorite date?
answer: '1969-07-20'
description: >-
array of simple objects with verbatim ClinSpark questions and
corresponding answers
items:
$ref: '#/components/schemas/VolunteerAnswer'
volunteerNotes:
type: array
example:
- Volunteer travels often
- Is afraid of needles
description: Simple notes that move to a volunteer notes section
items:
type: string
volunteerRaces:
type: array
example:
- American Indian or Alaska Native
description: Must match race names defined in ClinSpark
items:
type: string
volunteerSubstanceUse:
type: array
example:
- substanceUseCategory: Alcohol
name: Beer
useFrequency: Week
useConsumption: '5'
consumptionUnit: Glass/Bottle (.5L)
substanceUseStatus: Social
startDate: '2001'
lastConsumed: '2021-07-21'
substanceNotes: Enjoys heavy IPAs
description: >-
array of simple objects with verbatim ClinSpark questions and
corresponding answers
items:
$ref: '#/components/schemas/VolunteerSubstanceUse'
VolunteerUpdate:
type: object
properties:
id:
type: integer
format: integer
externalId:
type: string
example: '987123'
description: Unique identifier in originating recruitment system
title:
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
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
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
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
typeepochs:
string type: array
format: date-time lastUpdateditems:
type: string $ref: '#/components/schemas/EpochShort'
format:
date-time 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'
|
...