Seguimiento (llamadas salientes)

Inscribir pacientes en un protocolo y programar llamadas de seguimiento con cuestionario

El seguimiento es el flujo saliente: inscribes a un paciente en un protocolo y OlivIA lo llama para completar el cuestionario, aplicando la programación y los reintentos definidos en el protocolo.

​

1. Encuentra el protocolo

Necesitas la protocol_key (o el id) del protocolo en el que vas a inscribir.

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

Método	Ruta	Uso
GET	/v1/protocols	Lista protocolos. Query: search, status (draft|active|archived), limit (1–100, def. 50), offset.
GET	/v1/protocols/{idOrKey}	Obtiene un protocolo por UUID o protocol_key, con su versión activa.
DELETE	/v1/protocols/{idOrKey}	Archiva un protocolo. Requiere rol integrator/admin. Devuelve 409 si tiene inscripciones activas.

​

2. Inscribe al paciente

POST /v1/enrollments/enroll-patient crea (o reutiliza) el paciente por su teléfono, lo inscribe en el protocolo y programa la primera llamada saliente.

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" }
  }'

Campos del cuerpo:

Campo	Requerido	Notas
phone	sí	Formato E.164. Identifica y deduplica al paciente.
first_name, last_name	sí	Datos del paciente.
protocol_key o protocol_version_id	sí	Indica exactamente uno. Con protocol_key puedes añadir version; si lo omites, se usa la versión activa.
language	no	Etiqueta BCP-47 (p. ej. es, en). Por defecto, el idioma del protocolo.
preferred_timezone	no	Zona IANA para respetar las ventanas horarias.
started_at	no	Cuándo empieza el seguimiento (ISO 8601).
freq_config	no	Sobrescribe parcialmente la programación de la versión (cadencia, ventana de reintentos, franjas, rango de fechas, máximos).
custom_variable_values	no	Valores para las variables personalizadas del protocolo.

Respuesta 201:

{
  "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 es idempotente por diseño: si el paciente ya tiene una inscripción activa equivalente, se reutiliza; si los datos cambian, la inscripción anterior se reemplaza en cascada. No necesitas cabecera de idempotencia.

​

3. Programa cuestionarios adicionales (opcional)

Para lanzar otro cuestionario dentro de una inscripción existente:

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. Consulta el estado de la inscripción

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

Devuelve la inscripción y sus protocol_runs (cada uno con su questionnaire_status). Para leer respuestas, transcripción y grabación de cada llamada, consulta Resultados.

​

Programación (freq_config)

La cadencia de las llamadas la define el protocolo mediante freq_config: cadencia base, ventana y número de reintentos, franjas u horarios permitidos, rango de fechas y zona horaria. Puedes sobrescribirla por inscripción enviando un freq_config parcial en enroll-patient. OlivIA calcula la primera llamada y reprograma los reintentos automáticamente.