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

# List Appointments and Export to Calendar — /appointments

> GET /appointments returns follow-up appointments from a recovery plan. POST /appointments/{id}/calendar downloads an ICS file. Both require authentication.

AfterCare extracts every follow-up appointment from discharge paperwork and exposes them through two endpoints. Use `GET /appointments` to retrieve the structured list of appointments for a document. Use `POST /appointments/{appointmentId}/calendar` to download an ICS file that your patient can import directly into their calendar app.

***

## GET /appointments

Retrieve all follow-up appointments associated with a processed document.

### Query parameter

<ParamField query="documentId" type="string (UUID)" required>
  The document identifier returned by `POST /upload`. Only appointments that belong to this document **and** are owned by the authenticated user are returned.
</ParamField>

### Response — 200 OK

Returns an object with a `data` array of `Appointment` objects.

```json theme={null}
{
  "data": [
    {
      "id": "appt_01J4KXYZ",
      "date": "2024-10-01T09:00:00.000Z",
      "doctor": "Dr. Sarah Okonkwo",
      "specialty": "Cardiology",
      "location": "St. Mary's Medical Center, Suite 400",
      "notes": "Bring medication list. Fasting required.",
      "confidence": 91,
      "sourceLines": [88, 89, 90]
    }
  ]
}
```

<ResponseField name="data" type="Appointment[]">
  Array of extracted appointment objects.

  <Expandable title="Appointment object">
    <ResponseField name="id" type="string">
      Unique identifier for this appointment record. Use this value with `POST /appointments/{appointmentId}/calendar`.
    </ResponseField>

    <ResponseField name="date" type="string">
      The appointment date and time. When AfterCare can resolve an exact timestamp, this is an ISO 8601 string (e.g. `"2024-10-01T09:00:00.000Z"`). When the document contains only a human-readable date like `"first Monday in October"`, AfterCare preserves that string as-is. An empty string means no date information was found.
    </ResponseField>

    <ResponseField name="doctor" type="string">
      The name of the attending physician or care provider, as written in the document.
    </ResponseField>

    <ResponseField name="specialty" type="string">
      The medical specialty for this appointment, e.g. `"Cardiology"` or `"Physical Therapy"`.
    </ResponseField>

    <ResponseField name="location" type="string">
      The clinic or hospital name and address where the appointment takes place.
    </ResponseField>

    <ResponseField name="notes" type="string">
      Any preparation instructions or additional notes extracted from the document, e.g. `"Bring medication list. Fasting required."`.
    </ResponseField>

    <ResponseField name="confidence" type="number">
      AfterCare's extraction confidence for this appointment, expressed as an integer from `0` to `100`. A score of `100` means AfterCare is highly confident the information is accurate. A low score means the appointment details were ambiguous — always cross-reference those items against the original discharge document before presenting them to the patient.
    </ResponseField>

    <ResponseField name="sourceLines" type="number[]">
      The line numbers in the original uploaded document where this appointment was found. Use these to show the patient exactly where in their paperwork an appointment came from — for example, to highlight the relevant passage when a confidence score is low.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Appointments where AfterCare could not find a concrete date are still included in the response with an empty `date` field. These appointments are listed so your patient is aware of them, but they **cannot be exported to a calendar** — the `/calendar` endpoint will return `422` for undated appointments.
</Note>

### cURL example

```bash theme={null}
curl -G https://api.aftercare.app/appointments \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  --data-urlencode "documentId=550e8400-e29b-41d4-a716-446655440000"
```

***

## POST /appointments/{appointmentId}/calendar

Download an ICS calendar file for a specific appointment. The server generates a standard VCALENDAR event and returns it as a `text/calendar` attachment.

### Path parameter

<ParamField path="appointmentId" type="string" required>
  The `id` of the appointment to export. Must belong to the authenticated user, and the appointment's `date` field must contain a valid ISO 8601 datetime string (e.g. `"2024-10-01T09:00:00.000Z"`). Appointments with an empty or unparseable `date` cannot be exported — the server returns `422`.
</ParamField>

### Response — 200 OK

Returns a `text/calendar` file download (`appointment.ics`). The ICS file contains a single `VEVENT` populated with the appointment's date, specialty, and location.

```text theme={null}
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//AfterCare//EN
BEGIN:VEVENT
UID:appt_01J4KXYZ@aftercare
DTSTART:20241001T090000Z
SUMMARY:Cardiology appointment
LOCATION:St. Mary's Medical Center, Suite 400
END:VEVENT
END:VCALENDAR
```

<Tip>
  The downloaded `.ics` file opens natively in any major calendar application — including **Google Calendar**, **Apple Calendar**, and **Microsoft Outlook**. Prompt your user to open the file after downloading to add the appointment to their personal calendar with one click.
</Tip>

### cURL example

```bash theme={null}
curl -X POST https://api.aftercare.app/appointments/appt_01J4KXYZ/calendar \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  --output appointment.ics
```

***

## Error responses

| Status | Endpoint | Meaning |
| - | - | - |
| `401` | Both | Missing or invalid Bearer token. |
| `404` | `GET /appointments` | No recovery plan found for the given `documentId`, or the document does not belong to the authenticated user. |
| `404` | `POST /appointments/{id}/calendar` | Appointment not found, or it does not belong to the authenticated user. |
| `422` | `POST /appointments/{id}/calendar` | The appointment's `date` field is not a concrete ISO 8601 datetime and cannot be exported to a calendar. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.