Skip to content

List Appointments

Retrieve a paginated list of appointments within a specified date range for a specific doctor and clinic.

Endpoint

GET /apis/v1/appointment/calendar/events

Query Parameters

Parameter Type Required Description
start_date string Yes Start date in ISO 8601 format (e.g., 2025-05-09T04:00:00.000Z)
end_date string Yes End date in ISO 8601 format (e.g., 2025-05-10T03:59:59.999Z)
doctor_id integer Yes Unique identifier for the doctor
clinic_id integer Yes Unique identifier for the clinic
practice_id integer Yes Practice identifier (Required for fetch billing information): Send 0 if not available
page integer No Page number for pagination (default: 1)
size integer No Number of records per page (default: 300)

Example Request

curl 'https://provider.staging.spryhealth.care/apis/v1/appointment/calendar/events?end_date=2025-05-10T03:59:59.999Z&page=1&size=300&start_date=2025-05-09T04:00:00.000Z&doctor_id=27620&clinic_id=767&practice_id=1098' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: bearer {{auth_doctor}}'

Response

Success Response

Status Code: 200 OK

{
  "code": 2000,
  "data": {
    "total": 6,
    "pages": 1,
    "current": 1,
    "no_of_records": 6,
    "is_paged": true,
    "content": [
      {
        "appointment_id": 1385047,
        "case_title": "Pelvic - 25",
        "category_id": 3505,
        "check_in_time": null,
        "in_progress_at": null,
        "check_out_time": null,
        "comments": "",
        "date_time": "1754339400",
        "end_date_time": "1754341200",
        "doctor_id": 504841,
        "clinic_id": 549,
        "patient": {
          "patient_id": 515822,
          "name": "Shelby Zimmerman",
          "first_name": "Shelby",
          "middle_name": "",
          "last_name": "Zimmerman",
          "suffix": "",
          "alias": null,
          "date_of_birth": "1991-12-10",
          "sex": "FEMALE",
          "mobile": "+12673041496",
          "secondary_contact": null,
          "photo_url": null,
          "email_address": "shelby.a.zimmerman@gmail.com",
          "height": null,
          "weight": null,
          "address": {
            "line1": "",
            "line2": "",
            "landmark": "",
            "city": "",
            "state": "",
            "postal_code": "",
            "latitude": null,
            "longitude": null,
            "gps_link": null,
            "country": null,
            "plus_code": null,
            "place_id": null
          },
          "relation": null,
          "poc_status": null,
          "status": "ACTIVE",
          "comorbidities": null,
          "external_ref_id": null,
          "speciality_list": [],
          "organisation_id": 383,
          "preferred_language": null,
          "legacy_patient": true,
          "total_visits": 0,
          "payment_mode": null,
          "emergency_contacts": null,
          "last_appointment_id": 1385058,
          "additional_details": {
            "tags": null,
            "last_appointment_date": null,
            "visit_count": 0,
            "affected_body_parts": [],
            "diagnosis": [],
            "referring_physician_name": "",
            "referring_physician_phone_number": "",
            "referring_physician_fax_number": "",
            "referring_physician_npi": "",
            "dry_needling_consent": false,
            "insurance_payer": null,
            "comorbidities": null,
            "allergies": null,
            "mandatory_fields_completed": null
          }
        },
        "payment_mode": "INSURANCE_PAY",
        "affected_body_part_details": [],
        "recurring_appointment_id": 0,
        "spry_case_id": "SPRY_CASE_591025",
        "status": "CONFIRMED",
        "calendar_event_type": "APPOINTMENT",
        "insurance_card": {
          "insurance_card_id": 529619,
          "insurance_payer": {
            "payer_reg_id": 2838,
            "name": "United Health Care",
            "payer_type": null,
            "payer_state": null,
            "payer_id": "87726",
            "institutional_claims": null,
            "professional_claims": null,
            "era": null,
            "eligibility": null,
            "attachments": null,
            "workers_comp": false,
            "secondary_support": false,
            "eligibility_category": null,
            "clearing_house": null,
            "name_aliases": null,
            "credentialed": null,
            "edocument_support": false,
            "deleted": false
          },
          "insurance_number": null,
          "payer_alias_details": {
            "alias_id": "8f4037fb-5b8d-40fe-8265-bfd8d0bc4242",
            "alias_name": "United Health Care"
          },
          "payer_id": null,
          "insurance_type": null,
          "group_name": null,
          "group_number": null,
          "plan_name": null,
          "plan_type": null,
          "pre_authorization_number": null,
          "plan_start_date": null,
          "plan_end_date": null,
          "subscriber": null,
          "insurance_file": null,
          "patient_id": 515822,
          "insurance_associate_color_code": {
            "created_date": "2024-07-17T07:53:38",
            "updated_date": null,
            "id": 5,
            "primary_color": "#FF8766",
            "secondary_color": "#FFE0D8",
            "text_color": "#000000"
          },
          "deleted": false,
          "insurance_card_status": null,
          "insurance_card_type": "PRIMARY",
          "created_at": null,
          "updated_at": null,
          "work_comp_mvc_additional_details": null,
          "insurance_used_for": null,
          "insurance_card_eligibility_details_dto": null,
          "clinic_id": 0,
          "manual_co_pay": null,
          "additional_claim_information": null,
          "payer_type": null
        },
        "poc_created_at": null,
        "poc_expired_at": null,
        "poc_status": null,
        "visit_frequency": null,
        "treatment_duration_in_weeks": null,
        "copay_paid": null,
        "charge_entry_id": 1475628,
        "billing_status": "NONE",
        "patient_paid_amt": 0.0,
        "product_purchase_amt": null,
        "total_billed_amt": 0.0,
        "total_paid_amt": 0.0,
        "total_pending_balance": 0.0,
        "created_at": "2025-08-04T10:20:27",
        "visits_till_appointment": 0,
        "future_appointment_dates": null,
        "tele_health_url": null,
        "invoice_id": -1,
        "subscription_ref_id": -1,
        "subscribed_service_ref_id": 0,
        "type": "IN_CLINIC",
        "appointment_booked_by": null,
        "updated_at": null,
        "appointment_notes": null,
        "speciality": "PELVIC_EVALUATION",
        "dollar_colour": null
      }
    ]
  },
  "message": "Success"
}

Response Fields

Field Type Description
code integer Response status code (2000 for success)
data object Container for response data
data.total integer Total number of appointments
data.pages integer Total number of pages
data.current integer Current page number
data.no_of_records integer Number of records in current page
data.is_paged boolean Whether results are paginated
data.content array Array of appointment objects

Appointment Object Fields

Field Type Description
appointment_id integer Unique appointment identifier
case_title string Title/description of the case
category_id integer Appointment category identifier
check_in_time string/null Check-in timestamp
in_progress_at string/null Appointment start timestamp
check_out_time string/null Check-out timestamp
comments string Additional comments
date_time string Appointment start time (Unix timestamp)
end_date_time string Appointment end time (Unix timestamp)
doctor_id integer Doctor identifier
clinic_id integer Clinic identifier
patient object Patient information object
payment_mode string Payment method (INSURANCE_PAY, SELF_PAY)
affected_body_part_details array Body parts affected
recurring_appointment_id integer Recurring appointment identifier
spry_case_id string Spry case identifier
status string Appointment status (CONFIRMED, etc.)
calendar_event_type string Type of calendar event
insurance_card object/null Insurance card information
billing_status string Billing status (NONE, PENDING)
patient_paid_amt number Amount paid by patient
total_billed_amt number Total billed amount
total_paid_amt number Total amount paid
total_pending_balance number Pending balance
type string Appointment type (IN_CLINIC, TELEHEALTH)
speciality string Medical specialty
dollar_colour string/null Color code for financial status

Error Response

Status Code: 400 Bad Request / 401 Unauthorized 

{
  "code": 4000,
  "message": "Invalid date range or missing required parameters"
}

Notes

  • Date parameters must be in ISO 8601 format with timezone
  • The date_time and end_date_time in the response are Unix timestamps
  • Results are paginated when is_paged is true
  • Insurance card information may be null for self-pay patients
  • Financial information includes billing status and payment details