...
| Swagger integration | ||||
|---|---|---|---|---|
| ||||
openapi: 3.0.0
info:
description: >-
Allows for adding of volunteers, assignment and cancellation of
appointments.
version: 1.0.0-oas3
title: ClinSpark Recruit
servers:
- url: 'https://{customerId}.clinspark.com/api/v1/recruit'
variables:
customerId:
default: fhcommunity-15-demodev
description: Customer ID assigned by the service provider
- url: 'https://{ngrokPrefix}.ngrok.io/clinspark/api/v1/recruit'
variables:
ngrokPrefix:
default: 04f5b951df6d
description: first part of ngrok-assigned id
paths:
/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: int64
- 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:
type: object
properties: {}
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: int64
- 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'
'400':
description: Invalid username supplied
'404':
description: User not found
security:
- basicAuth: []
/listVolunteerAppointments:
get:
tags:
- recruit
summary: >-
Finds appointments for the given volunteer found by one of the
parameters supplied
parameters:
- 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'
'400':
description: Invalid username supplied
'404':
description: User not found
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: int64
- 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: object
'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: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
'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:
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
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
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: int64
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'
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'
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: int64
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 |
...