The Recruitment was API was originally introduced in early versions of ClinSpark and offers a basic set of capabilities to integrate ClinSpark with a recruitment website. It still exists today, and can be used in current (latest) ClinSpark releases. This document refers to the use of that basic Recruitment API.
However, current ClinSpark releases offer an updated API called Recruit. This newer API has an accompanying system setting, which can support more advanced workflows and website integration needs. That Recruit API is documented in it’s own separate section of the help site.
If there are questions about use of the API for recruitment website integration, please reach out to the Foundry Health team via the service desk.
This API is documented (and is testable using Swagger), below.
| Swagger integration | ||||
|---|---|---|---|---|
| ||||
openapi: 3.0.0
info:
title: ClinSpark Recruitment API
version: "1.0"
description: "This is REST API docummentation for Foundry Health's ClinSpark. To test API you would need to request `API User` credentials to use them to set Basic Authorization HTTP headers."
servers:
- url: 'https://{customerId}.clinspark.com/api/v1'
variables:
customerId:
default: community-dev
description: Customer ID assigned by the service provider
- url: 'https://{ngrokPrefix}.ngrok.io/clinspark/api/v1'
variables:
ngrokPrefix:
default: 04f5b951df6d
description: first part of ngrok-assigned id
paths:
/saveVolunteerRequest:
post:
security:
- basicAuth: []
summary: "Registers a volunteer's interest to participate studies."
description: ''
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VolunteerRequest'
description: a VolunteerRequest object
required: true
responses:
'200':
description: Success. The ID of the created object will be in the response body
'401':
description: Unauthorized. You must add Basic Authentication headers
'422':
description: Invalid request. There are input validation errors. Look at the JSON response for details
/saveVolunteerStudyInterest:
post:
security:
- basicAuth: []
summary: "Registers a volunteer's interest to participate in a particular study and/or cohort."
description: ''
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VolunteerStudyInterest'
description: a VolunteerStudyInterest object
required: true
responses:
'200':
description: Success. The ID of the created object will be in the response body
'401':
description: Unauthorized. You must add Basic Authentication headers
'422':
description: Invalid request. There are input validation errors. Look at the JSON response for details
components:
schemas:
VolunteerStudyInterest:
type: object
properties:
notes:
type: string
example: Some notes entered by the volunteer
description: any additional notes entered by the volunteer
abaAccount:
type: string
example: 00257 596
minLength: 6
maxLength: 16
description: "volunteer's ABA Account Number"
abaBank:
type: string
example: 91000019
minLength: 4
description: "volunteer's ABA Bank Number"
ibanAccount:
type: string
example: 844-0103700-34
minLength: 6
maxLength: 30
description: "volunteer's IBAN Account number"
ibanBank:
type: string
example: BE68844010370034
minLength: 12
maxLength: 30
description: "volunteer's IBAN Bank number"
generalPractitionerAddress:
type: string
example: '123 Yellobrick Lane. Antwerp, BE 60657'
minLength: 8
description: "volunteer's generalPractitioner address"
generalPractitionerPhoneNumber:
type: string
format: phone
example: '+13125551212'
minLength: 8
maxLength: 60
description: "volunteer's generalPractitioner phone number"
generalPractitioner:
type: string
example: David Hasslehoff
minLength: 6
maxLength: 100
description: "volunteer's generalPractitioner name"
country:
type: string
example: US
minLength: 2
maxLength: 3
description: "volunteer's ISO 3166-1 alpha-2 country code. See https://en.wikipedia.org/wiki/ISO_3166-2"
region:
type: string
example: IL
minLength: 2
description: "volunteer's region"
city:
type: string
example: Chicago
minLength: 2
description: "volunteer's city"
postalCode:
type: string
example: '60606'
minLength: 3
description: "volunteer's postal code"
address:
type: string
example: 123 Main St
description: "volunteer's postal address"
workPhone:
type: string
format: phone
example: +1312 555 1212
description: "volunteer's work phone number"
homePhone:
type: string
format: phone
example: +1312 555 1212
description: "volunteer's home phone number"
mobilePhone:
type: string
format: phone
example: +1312 555 1212
description: "volunteer's mobile phone number"
emailAddress:
type: string
format: email
minLength: 4
example: waldo@gmail.com
description: "volunteer's email address"
dateOfBirth:
type: string
format: date
example: '1979-12-31'
description: "volunteer's date of birth. Full-date notation as defined by RFC 3339, section 5.6"
lastName:
type: string
example: Good
description: "volunteer's last name"
middleName:
type: string
example: ''
description: "volunteer's middle name."
firstName:
type: string
example: Robin
description: "volunteer's first name"
cohorts:
type: array
items:
type: string
uniqueItems: true
description: list of cohorts the volunteer is interested in
genderMale:
type: boolean
example: true
description: "volunteer's gander, set to true for male, and false otherwise"
requestSource:
type: string
example: Facebook
description: How did the volunteer find out about study?
studyName:
type: string
minLength: 2
example: Demo Study
description: Study the volunteer is interested in
required:
- studyName
- firstName
- lastName
- genderMale
- dateOfBirth
VolunteerRequest:
type: object
properties:
notes:
type: string
example: Some notes entered by the volunteer
description: any additional notes entered by the volunteer
contactSource:
type: string
example: facebook
description: did the volunteer hear about this research facility?
vegetarian:
type: boolean
example: 'true'
description: is the volunteer a vegetarian?
allergies:
type: boolean
example: 'true'
description: does the volunteer have allergies?
contraceptionType:
type: string
example: Condom
description: type of contraception used by the volunteer. Note that this MUST match a value from the list configured in ClinSpark.
generalPractitionerAddress:
type: string
example: '123 Yellobrick Lane. Antwerp, BE 60657'
minLength: 8
description: "volunteer's generalPractitioner address"
generalPractitionerPhoneNumber:
type: string
format: phone
example: '+13125551212'
minLength: 8
maxLength: 60
description: "volunteer's generalPractitioner phone number"
generalPractitioner:
type: string
example: David Hasslehoff
minLength: 6
maxLength: 100
description: "volunteer's generalPractitioner name"
ibanBank:
type: string
example: '5678901'
description: "volunteer's IBAN Bank number"
ibanAccount:
type: string
example: '1234567'
description: "volunteer's IBAN account number"
abaBank:
type: string
example: '5678901'
description: "volunteer's ABA Bank number"
abaAccount:
type: string
example: '1234567'
description: "volunteer's ABA account number"
country:
type: string
example: US
minLength: 2
maxLength: 3
description: "volunteer's ISO 3166-1 alpha-2 country code. See https://en.wikipedia.org/wiki/ISO_3166-2"
region:
type: string
example: IL
description: "volunteer's region"
city:
type: string
example: Chicago
description: "volunteer's city"
postalCode:
type: string
example: '60606'
description: "volunteer's postal code"
address:
type: string
example: 123 Main St
description: "volunteer's postal address"
phoneNotes:
type: string
format: phone
example: Do not call after 9 PM
description: "notes about the volunteer's phone number"
workPhone:
type: string
format: phone
example: +1312 555 1212
description: "volunteer's work phone number"
homePhone:
type: string
format: phone
example: +1312 555 1212
description: "volunteer's home phone number"
mobilePhone:
type: string
format: phone
example: +1312 555 1212
description: "volunteer's mobile phone number"
emailAddress:
type: string
format: email
example: waldo@gmail.com
description: "volunteer's email address"
heightMeters:
type: number
format: double
minimum: 1
maximum: 3
example: '1.9'
description: "A volunteer's height in meters"
weightKilos:
type: number
format: double
minimum: 1
maximum: 370
example: 90
description: "A volunteer's weight in kilograms"
otherRace:
type: string
example: asian
minLength: 3
description: A volunteer race which is not on the list of standard races
dateOfBirth:
type: string
format: date
example: '1979-12-31'
description: "volunteer's date of birth. Full-date notation as defined by RFC 3339, section 5.6"
previousStudyParticipation:
type: boolean
example: true
description: Has the volunteer previously participated in a study
nextOfKin:
type: string
example: 'Uncle Bob, phone: +1312 456 7890'
description: "volunteer's next of kin info, freeform"
preferredLanguage:
type: string
example: Belgian
description: "volunteer's name suffix"
nationality:
type: string
example: Belgian
description: "volunteer's name suffix"
nameSuffix:
type: string
example: Jr
description: "volunteer's name suffix"
lastName:
type: string
example: Good
description: "volunteer's last name"
middleName:
type: string
example: ''
description: "volunteer's middle name"
firstName:
type: string
example: Robin
minLength: 2
description: "volunteer's first name"
title:
type: string
example: ''
minLength: 2
description: "volunteer's title in their name (like Dr)"
contactableByEmailCampaign:
type: boolean
example: true
description: Can they be contacted by Email Campaigns?
contactableByPhone:
type: boolean
example: true
description: Can they be contacted by Phone?
contactableBySms:
type: boolean
example: true
description: Can they be contacted by SMS?
genderMale:
type: boolean
example: true
description: "volunteer's gander, set to true for male, and false otherwise"
requestSource:
type: string
example: Facebook
description: How did the volunteer find out about study?
volunteerRaces:
type: array
items:
type: string
example: Asian
enum:
- AmericanIndianOrAlaskaNative
- Asian
- BlackOrAfricanAmerican
- NativeHawaiianOrOtherPacificIslander
- White
- OtherRace
- Unknown
example: [Asian, White]
volunteerRequestAnswers:
type: array
items:
$ref: '#/components/schemas/VolunteerRequestAnswer'
externalId:
type: string
example: '1234567'
maxLength: 256
description: 'This is the id of this same volunteer record in another system. This can be used for instance to later sync updates, but including the external ID along with the values that have changed.'
required:
- firstName
- lastName
- email
- race
- genderMale
- dateOfBirth
- previousStudyParticipation
VolunteerRequestAnswer:
type: object
properties:
question:
type: string
example: What is your favorite color
description: A custom volunteer question name defined in ClinSpark. This must EXACTLY match how it appears in ClinSpark, including capitalization.
answer:
type: string
example: Blue
description: The volunteer's answer, which can be a freeform string according to the API. However note that it must conform to any format restrictions defined within ClinSpark
required:
- question
- answer
securitySchemes:
basicAuth:
type: http
scheme: Basic
tags:
- name: recruitment
description: Volunteer Recruitment API |