Skip to main content
API docs by Redocly

Trialbee Incremental Candidate API (0.1.0)

E-mail: support@trialbee.com License: Private

Incremental Candidate API by Trialbee.

This public API can be used to get study-specific questionnaire settings for custom self-assessment solutions, and provides the ability to incrementally enroll a candidate.

Introduction

This API is documented in OpenAPI format. In addition to standard OpenAPI syntax we use a few vendor extensions.

Cross-Origin Resource Sharing

This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site. However, authentication will limit access to domain-scoped access only.

Authentication

Incremental Candidate API requires authentication in order to accept submissions. We use Bearer tokens (JWT) generated through OAuth 2.0. Tokens are linked to a specific domain, meaning that they are unusable from other domains.

Bearer Authentication

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

Create a new candidate record in Trialbee Honey

Creates a new candidate record in Honey, ready to be populated with answers and details.

Authorizations:
Bearer Authentication
Request Body schema: application/json

Data needed to create a new candidate

studyId
required
string (StudyId)

The study identifier where the candidate is applying to.

candidateId
required
string (CandidateId)

Identifier for the candidate in your system. This ID should be unique.

referrerToken
string (ReferrerToken)

A candidate can be recruited by many different vendors and users. In order to provide tracking within Honey, you can attribute a referrer to the candidate.

Example use-cases:

  • Trialbee Omnichannel with Patient Advocacy groups
  • Attribution based on whom entered them. Example pag-1-lauryn
  • Attribution based on how they entered. Example pag-1-poster, pag-1-facebook, pag-2-magazine
locale
string

The locale of the candidate, in IETF BCP 47 format.

Responses

Request samples

Content type
application/json
{
  • "studyId": "DEMO3",
  • "locale": "en-US",
  • "candidateId": "candidate-12345",
  • "referrerToken": "patient-advocacy-group-one"
}

Response samples

Content type
application/json
{ }

Answer a question for a candidate

Authorizations:
Bearer Authentication
path Parameters
candidateId
required
string
Example: candidate-12345

The candidate identifier for whom the question is being answered.

key
required
string
Example: question-67890

The key of the question being answered.

Request Body schema: application/json

Question answer payload

answer
required
string

The answer provided by the candidate to the question.

For radio button and checkbox questions, the format is stringified JSON for selected options:

'\{\"<key1>\": true, \"<key2>\": true\}'

Responses

Request samples

Content type
application/json
{
  • "answer": "Yes"
}

Response samples

Content type
application/json
{ }

Get eligibility status for a candidate

Retrieves the eligibility status and eligible sites for a candidate.

Authorizations:
Bearer Authentication
path Parameters
candidateId
required
string
Example: candidate-12345

The candidate identifier for whom eligibility is being checked.

Responses

Response samples

Content type
application/json
{
  • "eligibility": true,
  • "eligibleSites": [
    • "SITE-001",
    • "SITE-002"
    ]
}

Update candidate details

Replaces candidate PII, consents and preferences.

If the field pii is provided, an explicit data consent (consents.dataConsent: true) needs to be set in the payload. Partial updates are not supported.

Authorizations:
Bearer Authentication
path Parameters
candidateId
required
string
Example: candidate-12345

The candidate identifier for whom details are being updated.

Request Body schema: application/json
required

Candidate details payload

object
name
required
string
email
required
string <email>
phoneNumber
required
string <phone>
firstName
string
lastName
string
postalCode
string
timezone
string <tz>
object
dataConsent
required
boolean

Explicit consent for data processing. Needs to be true for detail update to succeed.

leadConsent
boolean

Consent for being contacted as a lead for the study.

lookalikeConsent
boolean

Consent for use in lookalike modeling.

object
contactHours
string
site
string

Preferred study site identifier. Should match one of the site IDs returned by the /rest/v1/candidates/{candidateId}/eligibility endpoint.

contactMethod
string
Enum: "Phone call" "SMS" "Email" "WhatsApp"

Responses

Request samples

Content type
application/json
{
  • "pii": {
    • "name": "Jane Doe",
    • "firstName": "Jane",
    • "lastName": "Doe",
    • "email": "jane.doe@example.com",
    • "phoneNumber": "+15551234567",
    • "postalCode": "12345",
    • "timezone": "Europe/Stockholm"
    },
  • "consents": {
    • "dataConsent": true,
    • "leadConsent": false,
    • "lookalikeConsent": false
    },
  • "preferences": {
    • "contactHours": "8-20",
    • "site": "SITE-001",
    • "contactMethod": "SMS"
    }
}

Response samples

Content type
application/json
{ }

Submit a candidate

Submits a candidate, preventing further changes.

Authorizations:
Bearer Authentication
path Parameters
candidateId
required
string
Example: candidate-12345

The candidate identifier being submitted.

Request Body schema: application/json
required

Submission payload

status
required
string
Enum: "DROPOUT" "COMPLETED"

Candidate submission status. Note: backend will check for eligibility to determine if candidate should be approved.

Responses

Request samples

Content type
application/json
{
  • "status": "COMPLETED"
}

Response samples

Content type
application/json
{ }

Get study questionnaire configuration

Returns study questionnaire configuration (questions, consent and UI config) for the given locale/language/country.

Authorizations:
Bearer Authentication
path Parameters
studyId
required
string

Study identifier for which to retrieve the questionnaire configuration.

query Parameters
locale
required
string

Locale used to localize questionnaire content (for example, en-US).

Responses

Response samples

Content type
application/json
{
  • "study": {
    • "id": "DEMO3",
    • "publicStudyName": "Genericazeram Demo"
    },
  • "textDirection": "ltr",
  • "questions": [
    • {
      • "id": "35302",
      • "type": "dateofbirth",
      • "question": "What is your year of birth? This will allow us to calculate your age.",
      • "description": "",
      • "key": "dob",
      • "options": {
        • "dateFormat": "yyyy"
        },
      • "items": null,
      • "visibleIf": null
      },
    • {
      • "id": "35298",
      • "type": "yesno",
      • "question": "Do you have a doctor’s diagnosis of Parkinson’s disease?",
      • "description": "",
      • "key": "diagnosis",
      • "options": { },
      • "items": null,
      • "visibleIf": null
      },
    • {
      • "id": "35299",
      • "type": "radiobutton",
      • "question": "Do your Parkinson’s symptoms cause you to be wheelchair bound or bedridden?",
      • "description": "",
      • "key": "wheelchair_bedridden",
      • "options": { },
      • "items": [
        • {
          • "key": "wheelchair",
          • "label": "Yes, wheelchair bound",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "bedridden",
          • "label": "Yes, bedridden",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "neither",
          • "label": "Neither of these",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          }
        ],
      • "visibleIf": "answer.diagnosis == 'true'"
      },
    • {
      • "id": "35300",
      • "type": "scale",
      • "question": "Please rate the severity of your symptoms from Parkinson's disease. ",
      • "description": "",
      • "key": "stiffness_shaking",
      • "options": { },
      • "items": [
        • {
          • "key": "1",
          • "label": "Very low",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "5",
          • "label": "Very high",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          }
        ],
      • "visibleIf": "answer.diagnosis == 'true'"
      },
    • {
      • "id": "35301",
      • "type": "checkbox",
      • "question": "Are you currently taking any of the following levodopa medication for Parkinson’s?",
      • "description": "Please select all that you are taking.",
      • "key": "levodopa_meds",
      • "options": { },
      • "items": [
        • {
          • "key": "sinemet",
          • "label": "Sinemet",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "sinemet_cr",
          • "label": "Sinemet CR",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "rytary",
          • "label": "Rytary",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "inbrija",
          • "label": "Inbrija",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "stelavo",
          • "label": "Stalevo",
          • "inlineText": null,
          • "unique": null,
          • "maxLength": null
          },
        • {
          • "key": "none",
          • "label": "None of these",
          • "inlineText": null,
          • "unique": true,
          • "maxLength": null
          }
        ],
      • "visibleIf": "answer.diagnosis == 'true'"
      }
    ],
  • "consent": {
    • "id": "4890",
    • "questions": [
      • {
        • "id": "42031",
        • "type": "dataconsent",
        • "question": "MANDATORY. I consent to and give permission for Trialbee on behalf of Generica Ltd to process my personal data including the health information that I have given. For more information, view our privacy policy and the full consent. ",
        • "description": "I consent to and give permission to Trialbee to process and use my personal data on behalf of Generica Ltd as the data controller for my personal data, including my Identity Data, Contact Data, and Health Data as described in the [privacy policy](https://trialbee.com/privacy-policy/), for the purposes of completing my registration request and to consider whether I am eligible/suitable for participating in a clinical research study, related to a clinical investigation, or clinical support program sponsored by Generica Ltd.\n\nI understand that my personal data may be shared with healthcare providers and medical researchers involved in the pre-screening process. \n\nI understand that I have the right to withdraw my consent at any time. To withdraw my consent, I can contact [Contact Information]. Upon withdrawal, Trialbee will cease processing my personal data and will delete or anonymize my data in accordance with applicable laws and regulations. Withdrawal of consent will not affect the lawfulness of processing based on consent before its withdrawal.\n\nTo learn more about how Trialbee stores and uses my data, I can read the full privacy policy [here](https://trialbee.com/privacy-policy/).\n",
        • "key": "data_consent",
        • "options": { },
        • "items": null,
        • "visibleIf": null
        },
      • {
        • "id": "42032",
        • "type": "leadconsent",
        • "question": "OPTIONAL. I consent to Trialbee processing my personal and health data for Generica Ltd to contact me regarding future studies I may be suitable for. ",
        • "description": "I consent to and give permission to Trialbee to process and use my personal data on behalf of Generica Ltd as the data controller for my personal data, including my Identity Data, Contact Data, and Health Data as described in the privacy policy [here], for the purposes of considering my suitability for future clinical trials sponsored by Generica Ltd.\n\nI understand that my personal data may be shared with healthcare providers and medical researchers involved in the pre-screening process. My data will be retained for 3 years unless I opt to re-consent when given the option.\n\nI understand that I have the right to withdraw my consent at any time using the link in the welcome email received upon registration. Upon withdrawal, Trialbee will cease processing my personal data and will anonymize my data in accordance with applicable laws and regulations. \n\nWithdrawal of consent will not affect the lawfulness of processing based on consent before its withdrawal. To learn more about how Trialbee stores and uses my data, I can read the full privacy policy [here].\n",
        • "key": "lead_consent",
        • "options": { },
        • "items": null,
        • "visibleIf": null
        }
      ],
    • "criteria": "[{\"criteria\":{\"data_consent\":\"true\"},\"studyIds\":[\"DEMO3\"]}]"
    },
  • "config": {
    • "welcomeImage": null,
    • "colorMain": "#146b98",
    • "colorLight": "#f8f7f3",
    • "fontInclude": null,
    • "fontFamily": null,
    • "messages": {
      • "ContactDetails.PostalCode": "Zip code"
      },
    • "contactForm": [
      • {
        • "name": "name",
        • "type": "name",
        • "isDefault": true
        },
      • {
        • "name": "email",
        • "type": "email",
        • "confirm": false,
        • "isDefault": true
        },
      • {
        • "name": "phone",
        • "type": "phone",
        • "isDefault": true
        },
      • {
        • "name": "postalCode",
        • "type": "postalCode",
        • "isDefault": true
        },
      • {
        • "name": "preferredContactHours",
        • "type": "select",
        • "options": [
          • "8-20",
          • "8-12",
          • "12-16",
          • "16-20"
          ],
        • "isDefault": false,
        • "defaultValue": "8-20"
        },
      • {
        • "name": "preferredContactWay",
        • "type": "select",
        • "options": [
          • "Phone call",
          • "SMS",
          • "Email",
          • "WhatsApp"
          ],
        • "isDefault": false,
        • "defaultValue": "Phone call"
        }
      ],
    • "steps": [
      • "questionnaire",
      • "siteSelector",
      • "contactDetails",
      • "completed"
      ],
    • "autoScroll": true,
    • "customPages": {
      • "completed": {
        • "title": "Registration completed! ",
        • "text": "Thank you for your interest. An email has been sent to ${email}. You will be contacted by the study medical team shortly to further assess your eligibility and potential study participation.",
        • "subText": "Should you have any questions or concerns, please email us at support@trialbee.com. ",
        • "buttonText": null,
        • "buttonAction": null
        },
      • "leave": {
        • "title": "Are you sure you want to leave?",
        • "text": "Any information you have entered in this self-assessment will not be saved.",
        • "subText": null,
        • "buttonText": null,
        • "buttonAction": null
        },
      • "ineligible": {
        • "title": "Thank you for taking the time to learn about this study and answering our questions. ",
        • "text": "Unfortunately, one or more of your responses indicates that you do not meet the requirements to take part in the study, at this time.\n\nDo you want to sign up for future studies you may be suitable for? Sign up below!",
        • "subText": null,
        • "buttonText": "Sign up for future studies!",
        • "buttonAction": "https://demotrialbee.com/lead-registration/"
        }
      }
    },
  • "messages": {
    • "ClinicForm.FindNearestClinic": "Find nearest clinic",
    • "ClinicForm.SelectClinic": "Select a preferred clinic you would like to visit if you were to take part in the study"
    }
}