Fires when an order is held until the patient completes a follow-up visit — typically a subscription refill that requires a check-in before it can be filled. Telegra notifies the patient by SMS and email at the same time. ownerEntity is the Patient; targetEntity is the Order. The eventType is order_visit_required.
Unlike order_created, this event concerns a returning patient whose next fill is already blocked. The visit link is the action item.
Field guarantees
| Field | Guarantee |
|---|---|
eventData.orderLink | ⚠️ Present whenever the link could be generated — same URL sent to the patient |
order_id in v2 | ✅ Always delivered (ORDER allowlist) |
order_link in v2 | ⚠️ Delivered only when orderLink was resolved |
v1 payload (legacy)
{
"_id": "event::8d367e3b-xxxx-xxxx-xxxx-3c6b7dfb804a",
"ownerEntityModel": "Patient",
"targetEntityModel": "Order",
"deleted": false,
"ownerEntity": "pat::117eb3b9-xxxx-xxxx-xxxx-9424274b5425",
"targetEntity": "order::e5576e92-xxxx-xxxx-xxxx-3c3173a3fb82",
"eventTitle": "A follow up visit is required on this order. The patient was notified via SMS and email.",
"eventType": "order_visit_required",
"eventData": {
"orderLink": "https://visit.example.com/shortUrl/a1b2c3d4e5f6a7b8"
},
"createdAt": { "$date": "2024-08-16T12:28:38.044Z" },
"updatedAt": { "$date": "2024-08-16T12:28:38.044Z" },
"__v": 0
}eventData field | Type | Always? | Notes |
|---|---|---|---|
orderLink | string | ⚠️ | The follow-up visit URL sent to the patient. Omitted if the link could not be generated. Expires 7 days after it is issued. |
v2 payload
Sanitized envelope. orderLink aliases to order_link. Patient name/email/phone are not included (PHI blocklist); use envelope patient_id / patient_external_id.
{
"event_type": "order_visit_required",
"event_id": "event::8d367e3b-xxxx-xxxx-xxxx-3c6b7dfb804a",
"api_version": "2026-08-17",
"timestamp": "2026-05-30T14:00:00.000Z",
"timestamp_epoch": 1780149600,
"affiliate_id": "aff::xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"patient_id": "pat::117eb3b9-xxxx-xxxx-xxxx-9424274b5425",
"patient_external_id": "ext-patient-123",
"patient_marketing_consent": false,
"is_returning_patient": true,
"order_id": "order::e5576e92-xxxx-xxxx-xxxx-3c3173a3fb82",
"order_status": "started",
"order_link": "https://visit.example.com/shortUrl/a1b2c3d4e5f6a7b8"
}| Field | Delivered in v2 | Notes |
|---|---|---|
| Envelope + patient identity | ✅ | Includes timestamp_epoch |
order_id, order_status | ✅ | Resolved from the order |
order_link | ⚠️ | Same link sent to the patient in the SMS/email |
attribution, journey_id | ⚠️ | See Attribution Passthrough |
Using the visit link
The order stays on hold until the visit is completed, so this is a good trigger for your own follow-up sequence. Cancel that sequence on order_submitted, which fires once the patient finishes the visit. Unlike order_created, journey_completed is not an alternative here — this visit is attached to the order rather than to a journey, so no journey event will arrive for it.
The link expires 7 days after it is issued, so a sequence that runs past a week should stop rather than send a dead link. If Telegra sends its own reminder for the order in the meantime, order_reminder_sent carries the link again with its 7-day window reset — an affiliate-triggered resend does the same, and neither depends on a project setting. Don't build your timing around it, though: only Telegra's scheduled repeat reminders are automatic, and those need the order's project to have a reminder frequency configured.