Skip to main content
API docs by Redocly

Trialbee Candidate API (1.1.0)

E-mail: [email protected]

Candidate API by Trialbee.

This public API can be used to roll your own custom self-assessment solution using standard HTML-forms, Wordpress forms or any other custom integration.

Introduction

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

Rate Limiting

To ensure system stability and fair usage, the API enforces the following limits:

  • Default Limit: 100 candidate submissions per hour
  • Scope: Limits apply per API key/study
  • Exceeding Limits: Requests beyond the limit return HTTP 429 (Too Many Requests)

Need Higher Limits? Contact your assigned Trialbee Project Manager to discuss temporary or permanent limit increases for high-volume studies.

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.

Authentication

Candidate API requires authentication in order to accept submissions. We currently support an API-key based approach passed in the URL.

ApiKeyAuth

Security Scheme Type: API Key
Query parameter name: credential

candidates

Public API operations available to all studies that have enabled the API-functionality.

Create a new candidate record in Trialbee Honey

Authorizations:
ApiKeyAuth
query Parameters
credential
required
string <password>
Example: credential=B886CCEA-4592-11EE-B632-ACDE48001122

API Token provided by Trialbee. Note that the token might be locked to certain origins.

Request Body schema: application/json

Submit a single Candidate

object (Candidate)
name
string

The full name of the candidate.

email
string <email>

An email address satisfying the regular expression ^\S+@\S+\.\S+$.

phoneNumber
string

Phone number expressed in E.164-format. E.164 numbers can have a maximum of fifteen digits and are written as: [+][country code][national destination code][subscriber number].

They can be validated using the regular expression ^\+[1-9]\d{1,14}$.

Note: This field has a relaxed input validation and the API will try to convert national formatted phone numbers to E.164 using country field.

postalCode
string <= 20 characters

Postal/zip code. The postal code is used by users of Trialbee Honey to help determine the closest site.

country
string <= 10 characters

Country expressed by any of the ISO-3166 recognized codes: Alpha-2, Alpha-3 or numeric. Codes may be converted over time to its most specific version.

language
string <= 10 characters

Language expressed by any of the ISO 639 (1&2) recognized codes (Wikipedia). Codes may be converted over time to its most specific version.

dateOfBirth
string

Date of birth expressed full-date format, i.e. YYYY-MM-DD. For convenience, we also allow date-month (2023-08) and date-fullyear (2023).

object (CandidatePreferences)
preferredContactHours
string
Enum: "morning" "afternoon" "evening" "allDay"

This field indicates the candidate's preferred time frame for contact, helping ensure communication efforts align with the candidate's convenience. It's important to note that this preference makes contact efforts more efficient, considerate, and likely more successful, providing a better candidate experience.

The time suggestion should be submitted as the period of the day during which the candidate prefers to be contacted.

Note: this is merely a preference and not a guarantee of exactly when contact will be made.

preferredContactWay
string
Enum: "email" "phoneCall" "sms" "whatsapp"

This field allows the candidate to specify their preferred way of being contacted.

Please note that the chosen contact way will not be automatically validated. In cases where the user selects a contact way but does not provide the corresponding details (eg.: selecting 'phoneCall' but not providing a phone number), no error would be thrown. Ensure necessary data validation is performed to avoid such scenarios.

site
string

Currently supports a sitesou identifier

object (CandidateConsent)
dataConsent
required
boolean

This field pertains to a candidate's explicit data consent, which all API consumers are mandatorily required to obtain. The consent language should encompass in-depth details concerning the data utilization methods.

It's essential to gain extensive insight into the requirements for GDPR consent, which can be referred to via GDPR.eu.

The inclusion of the dataConsent field in this schema is not optional. If absent in requests, any non-personal data can still be processed. However, the candidate's personally identifiable information will be categorically excluded.

Please note, in this field true signifies that the user has given consent, whereas false indicates that the user has declined or not given consent.

lookalikeConsent
boolean
Default: false

If a candidate agrees to participate in look-alike modelling, this field should be set to true.

For GDPR-subjects, ensure that the candidate has given explicit consent for this purpose.

thirdPartyConsent
boolean
Default: false
object (SelfAssessment)

Answers to self assessment questions is used both for qualifying a candidate into a study and for reporting regarding how individual questions are answered. This block of the API supports different operating modes.

object (SelfAssessmentEligibility)

Externally assessed candidates: If the API is been configured to trust externally computed eligibility, then this field will be considered when assigning status to the candidate object.

Trialbee assessed candidates: If the API is been configured to calculate eligibility based on provided answers, then this field fill be discarded before assigning status to the candidate object.

status
string
Enum: "ineligible" "eligible" "unknown"
object (SelfAssessmentQuestions)

Add information to each submission on what the question was for the corresponding answers provided in selfAssessment.answers.<key>.

This block is useful if you import historically collected questionnaires or if the API operation mode is set to Externally assessed .

Note: If API operation mode is set to Trialbee assessed, this block is redundant.

required
Array of objects
Array
Any of
key
required
string
type
required
string
Enum: "text" "number" "boolean" "singleSelect" "multiSelect"
title
required
string
object (SelfAssessmentAnswers)

Answers are a collection of key/values where the key is the name of the field and value is the answer provided by the user.

Note: If API has been configured to use Trialbee hosted questionnaire then all fields must be sent no matter if the user was given the possibility to provide an answer to the question (i.e. conditional display of question). If the questionnaire specifies five questions like the example, and it does not, parsing issue will arise and the submitted information will need manual investigation.

additional property
TextAnswer (string) or BooleanAnswer (boolean) or NumberAnswer (number) or SingleSelectAnswer (object) or MultiSelectAnswer (object)
Any of
string (TextAnswer)
object (Attribution)
referrerToken
string

A Candidates 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
object (ClientInformation)
userAgent
string
browserLocales
string
referringUrl
string <url>

The referring URL aims to pass information about where the user are at the time when they start the sign-up. In many cases, when using Trialbee Self-assessment widget on single study landing pages, this information is simply the output of javascript window.location.href (see MDN).

Note: This field may hold information about UTM-data. If this information is of interest in Honey, pass UTM-fields as part of the query string, i.e. https://mystudy.com/studyPage?utm_source=facebook&utm_medium=cpc. See guide for

object (ExternalIdentifiers)

Add external identifiers to the candidate. This is useful if you want to link the candidate to an external system.

property name*
additional property
string

Add external identifiers to the candidate. This is useful if you want to link the candidate to an external system.

Key name: Since the external identifiers are not unique in Honey, it's recommended to use a prefix to avoid collisions. If your company name is ACME, and the corresponding domain name is acme.com, you could use com.acme.referralId as key.

Responses

Request samples

Content type
application/json
{
  • "candidate": {
    • "name": "Petro Prokopovych",
    • "email": "[email protected]",
    • "phoneNumber": "+46701234567",
    • "postalCode": "211 40",
    • "country": "SE",
    • "language": "swe",
    • "dateOfBirth": "2023-08-15"
    },
  • "preferences": {
    • "preferredContactHours": "morning",
    • "preferredContactWay": "phoneCall",
    • "site": "SE-0002"
    },
  • "consent": {
    • "dataConsent": true,
    • "lookalikeConsent": false,
    • "thirdPartyConsent": false
    },
  • "selfAssessment": {
    • "eligibility": {
      • "status": "ineligible"
      },
    • "definition": {
      • "questions": [
        • {
          • "key": "30_years",
          • "type": "text",
          • "title": "Are you at least 30 years of age?"
          }
        ]
      },
    • "answers": {
      • "30_years": true,
      • "diagnosis": true,
      • "wheelchair_bedridden": true,
      • "stiffness_shaking": 2,
      • "levodopa_meds": {
        • "Sinemet": true,
        • "Rytary": true
        }
      }
    },
  • "attribution": {
    • "referrerToken": "patient-advocacy-group-one"
    },
  • "clientInformation": {},
  • "externalIdentifiers": {
    • "com.acme.project.referralId": "b886ccea-4592-11ee-b632-acde48001122",
    • "com.acme.project.patientId": "patient-42"
    }
}

Response samples

Content type
application/json
{
  • "candidateId": "TBX1-123456",
  • "submissionId": "1-654502ef-01c39e98406a093a0ca5c585",
  • "eligibility": "eligible"
}