Table of Contents

style	none

Notice

Note

The Recruitment API will be deprecated in a future release of ClinSpark. Our intention is to have a single API capable of delivering on all use cases for recruitment workflows, focusing on more flexible and dynamic capabilities that the ‘Recruit’ API can offer.

Recruit API

Customers using the Recruitment API are encouraged to explore use of the Recruit API, which can support more advanced workflows and website integration needs.

We intend to provide advanced warning and further information to our customers when a decision is made to fully end support for Recruitment API, so transition plans can be established.

Introduction

The Recruitment 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 While it still exists in current releases, it will be deprecated eventually (see notice above).

This Recruitment API is documented (and is testable using Swagger), below.

...

For information about how to use the

...

Users will need to have an account on the ClinSpark instance used (‘server’)
The user must be allowed to use HTTP Basic Authentication
1. Image Removed
For non-superdministrator users, they must have the api Role Action in one of their assigned Roles

Interactive API documentation

embedded Swagger UI and prerequisites for use, refer to this article:

https://foundryhealth.atlassian.net/wiki/spaces/DOCS/pages/3700260906/ClinSpark+APIs#Prerequisites-for-use

Interactive API documentation

The current version of the Swagger UI is setup to demonstrate use with ClinSpark accounts that use Basic HTTP authentication.

Swagger integration

showCommonExtensions	true
supportedSubmitMethods	get, post

openapi: 3.0.0
info:
  title: ClinSpark Recruitment API
  version: "1.0"
  description: "This is REST API

...

documentation for

...

the ClinSpark Recruitment API. To test this API, you

...

need to

...

obtain appropriate `API User` credentials to use them

...

with 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

Versions Compared

Old Version 7

New Version Current

Key

Notice

Introduction

Interactive API documentation

Interactive API documentation

Page Comparison

Versions Compared

Old Version 7

New Version Current

Key

Notice

Introduction

Interactive API documentation

Interactive API documentation