List Appointments and Export to Calendar — /appointments

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

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.

Response — 200 OK

Returns an object with a data array of Appointment objects.

{
  "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]
    }
  ]
}

Appointment[]

Array of extracted appointment objects.

Show Appointment object

string

Unique identifier for this appointment record. Use this value with POST /appointments/{appointmentId}/calendar.

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.

string

The name of the attending physician or care provider, as written in the document.

string

The medical specialty for this appointment, e.g. "Cardiology" or "Physical Therapy".

string

The clinic or hospital name and address where the appointment takes place.

string

Any preparation instructions or additional notes extracted from the document, e.g. "Bring medication list. Fasting required.".

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.

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.

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.

cURL example

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

POST /appointments//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

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.

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.

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

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.

cURL example

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.

Overview

Endpoints

List Appointments and Export to Calendar — /appointments

GET /appointments

Query parameter

Response — 200 OK

cURL example

POST /appointments//calendar

Path parameter

Response — 200 OK

cURL example

Error responses

​GET /appointments

​Query parameter

​Response — 200 OK

​cURL example

​POST /appointments//calendar

​Path parameter

​Response — 200 OK

​cURL example

​Error responses

GET /appointments

Query parameter

Response — 200 OK

cURL example

POST /appointments//calendar

Path parameter

Response — 200 OK

cURL example

Error responses