eConsent

With eConsent on, a trial has one or more consent forms — the participant information sheet, eligibility criteria and consent statements a person reads and agrees to — and a consent record for each person who has done so. Setting up eConsent explains the forms from the interface's point of view; these endpoints let you manage the forms and read the records.

The consent flow itself — the pages a person goes through to read, verify their contact details and sign — is driven by the join pages and is not part of the API.

Reading and editing forms needs trial.readConsentSettings / trial.admin; reading consent records needs trial.readTrialConsents. Turning eConsent on is a trial setting (eConsentEnabled); eConsentClosed stops new people consenting while keeping the records.

Endpoints

Method Path Description
GET /trials/<trialId>/consentDocuments The trial's consent forms, as {"documents": [...]}, newest first, each with its consentCount.
POST /trials/<trialId>/consentDocuments Create a consent form.
PATCH /trials/<trialId>/consentDocuments/<documentId> Update a form.
DELETE /trials/<trialId>/consentDocuments/<documentId> Delete a form. Refused while consent records reference it.
GET /trials/<trialId>/consents?page=1&query= Consent records, 30 to a page, as {"consents": [...], "total": n}. query matches on the name, email, phone or WhatsApp number — case-insensitive, and matched anywhere in the value. Listing is logged.
GET /trials/<trialId>/consentSessions?page=1&query=&state=&identityVerification=&includeEmpty= Every consent session — completed or not — 20 to a page, newest first, as {"sessions": [...], "total": n, "perPage": 20}. See Consent sessions. Listing is logged.

POST /trials/<trialId>/consentDocuments and PATCH /trials/<trialId>/consentDocuments/<documentId>:

Field Type Notes
document string The participant information sheet, as HTML. 5–100,000 characters.
pisMode string Which information sheet the form shows: text (the default, document) or pdf (the uploaded PDF). The other is kept but not shown. pdf needs a pisFile.
pisFile string The information sheet as a PDF: the stored fileName from an upload with forType=trial. Must be a PDF of up to 10MB that opens without a password; the form keeps its own copy under a new stored name, which is what pisFile reads back as. null removes it. Forms returned by the API carry pisFileName, pisFileHash (SHA-256) and a short-lived pisFileUrl.
pisFileName string The PDF's file name as shown to staff.
formKey string Letters and digits only. Identifies the form in its link (https://app.trialflare.com/consent/<trialCode>/<formKey>); default if omitted. Unique within the trial.
name string Up to 200 characters. Shown to staff.
eligibilityCriteria string Criteria the person confirms they meet.
conditions list The consent statements: each {"id", "title", "description", "optional"}.
verificationMethods list Which of email, phone, whatsapp the person may verify with. At least one.
requiredVerificationMethods list Those they must verify.
identityVerificationEnabled boolean Ask for photo-ID verification.
connectContactDetails boolean Copy the verified contact details onto the participant record.
postConsentText string Shown after signing.
postConsentStage, postConsentStageButtonLabel stage _id, string A stage (a screening questionnaire, say) to offer straight after consent.
postSubmissionText string Shown after that stage is submitted.
notificationEmail, withdrawalEmail email Addresses told when someone consents, or withdraws.

Each record in GET /trials/<trialId>/consents has who consented (fullName, and the email, phone or whatsapp they verified), createdAt, which consentDocument they signed, what they confirmed (consentGiven, trialConditionsConsentGiven, eligibilityCriteriaConfirmed, and conditionConfirmations keyed by condition id, with any initials given), the signed PDF (file, with its fileHash), and their screeningResponses where a stage followed consent. Where the form was signed through the newer session-based flow, sessionEvents is the timeline of what they did on each page. Contact details are included only for viewers with the personal-information permission.

A session is one attempt at a consent form, from opening the link to signing (or not). GET /trials/<trialId>/consentSessions lists them, including the ones that never became a consent record, such as those whose identity check failed. It needs trial.readTrialConsents and trial.read, since it holds the details of people who have not consented.

Filters: state is completed, in_progress or expired (a session lasts 24 hours); identityVerification is any (sessions with an identity check) or failed (with a failed one); query matches the name, email, phone or WhatsApp number entered, case-insensitively and anywhere in the value. Sessions where nothing was entered and no identity check was started are left out unless includeEmpty=true.

Each session has createdAt, expiresAt, completedAt, state, the consentDocument (and its consentDocumentFormKey), the fullName entered, and:

  • contacts — one entry per contact method entered: method, the value, codeSentTo / codeSentAt if a code was sent, verified / verifiedAt, failedAttempts, and locked once too many wrong codes were tried.
  • identityVerifications — every identity check started in the session, oldest first: status (pending_verification, submitted, verified or failed), declineReasons (the provider's reason codes, such as DOCUMENT_INCOMPLETE), declineComments (its explanation to the applicant, one per reason), and the names read from the ID.
  • consent — {_id, createdAt} of the consent record the session produced, or null.
  • events — the session timeline, as sessionEvents on a consent record.