Follow-up (outbound calls)

Enroll patients in a protocol and schedule outbound follow-up questionnaire calls

Follow-up is the outbound flow: you enroll a patient in a protocol and OlivIA calls them to complete the questionnaire, applying the scheduling and retries defined in the protocol.

1. Find the protocol

You need the protocol’s protocol_key (or id) to enroll into it.

curl "https://{your-prod-endpoint}/v1/protocols?status=active" \
  -H "Authorization: Bearer oc_sk_..."

Method	Path	Use
GET	/v1/protocols	List protocols. Query: search, status (draft|active|archived), limit (1–100, default 50), offset.
GET	/v1/protocols/{idOrKey}	Get a protocol by UUID or protocol_key, with its active version.
DELETE	/v1/protocols/{idOrKey}	Archive a protocol. Requires role integrator/admin. Returns 409 if it has active enrollments.

2. Enroll the patient

POST /v1/enrollments/enroll-patient creates (or reuses) the patient by phone, enrolls them in the protocol, and schedules the first outbound call.

curl -X POST "https://{your-prod-endpoint}/v1/enrollments/enroll-patient" \
  -H "Authorization: Bearer oc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[phone]",
    "first_name": "Ana",
    "last_name": "García",
    "protocol_key": "seguimiento-epoc",
    "language": "es",
    "preferred_timezone": "Europe/Madrid",
    "custom_variable_values": { "medico": "Dra. Menéndez" }
  }'

Body fields:

Field	Required	Notes
phone	yes	E.164 format. Identifies and deduplicates the patient.
first_name, last_name	yes	Patient data.
protocol_key or protocol_version_id	yes	Provide exactly one. With protocol_key you may add version; if omitted, the active version is used.
language	no	BCP-47 tag (e.g. es, en). Defaults to the protocol’s language.
preferred_timezone	no	IANA zone, to honor time windows.
started_at	no	When follow-up begins (ISO 8601).
freq_config	no	Partially overrides the version’s scheduling (cadence, retry window, slots, date range, maximums).
custom_variable_values	no	Values for the protocol’s custom variables.

201 response:

{
  "data": {
    "id": "…enrollmentId…",
    "patient_id": "…",
    "protocol_version_id": "…",
    "status": "active",
    "language": "es",
    "started_at": "2026-08-05T09:00:00Z",
    "freq_config": { },
    "custom_variable_values": { "medico": "Dra. Menéndez" }
  }
}

enroll-patient is idempotent by design: if the patient already has an equivalent active enrollment it is reused; if the data changes, the previous enrollment is cascade-replaced. No idempotency header is needed.

3. Schedule additional questionnaires (optional)

To launch another questionnaire within an existing enrollment:

curl -X POST "https://{your-prod-endpoint}/v1/protocol-runs" \
  -H "Authorization: Bearer oc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enrollment_id": "…",
    "scheduled_at": "2026-08-12T10:00:00Z",
    "language": "es"
  }'

4. Check the enrollment

curl "https://{your-prod-endpoint}/v1/enrollments/{enrollmentId}" \
  -H "Authorization: Bearer oc_sk_..."

Returns the enrollment and its protocol_runs (each with its questionnaire_status). To read answers, transcript, and recording for each call, see Results.

Scheduling (freq_config)

Call cadence is defined by the protocol via freq_config: base cadence, retry window and count, allowed slots/hours, date range, and time zone. You can override it per enrollment by sending a partial freq_config in enroll-patient. OlivIA computes the first call and reschedules retries automatically.