> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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**.

```bash theme={null}
curl -X POST "https://{your-prod-endpoint}/v1/enrollments/enroll-patient" \
  -H "Authorization: Bearer oc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+34612345678",
    "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:

```json theme={null}
{
  "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" }
  }
}
```

<Info>
  `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.
</Info>

## 3. Schedule additional questionnaires (optional)

To launch another questionnaire within an existing enrollment:

```bash theme={null}
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

```bash theme={null}
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](/olivia/en/api/resultados).

## 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.