Appointments Endpoints

Create, read, and manage appointment records

Overview

The Appointments API allows you to schedule appointments, retrieve appointment data, and update appointment status. This is useful for CRM integrations that need to book medical appointments.

API Endpoints

POSThttps://server.nyraai.io/api/external/appointments

Create a new appointment for a patient

Permission: appointments:write

Headers

x-api-keyrequired

API key

x-api-secretrequired

API secret

Authorizationrequired

Bearer hospital token

Content-Typerequired

application/json

Request Body

{
  "patient_id": "<patient-uuid>",
  "patient_phone": "+919876543210",
  "patient_name": "Ravi Kumar",
  "doctor_id": "<doctor-uuid>",
  "branch_id": "<branch-uuid>",
  "appointment_date": "2026-04-15",
  "appointment_time": "09:30:00",
  "type": "CONSULTATION",
  "notes": "Booked via CRM",
  "booking_source": "MANUAL"
}

Response

{
  "success": true,
  "data": {
    "appointment_id": "appointment-uuid"
  }
}
GEThttps://server.nyraai.io/api/external/appointments

List appointments with filtering and pagination

Permission: appointments:read

Headers

x-api-keyrequired

API key

x-api-secretrequired

API secret

Authorizationrequired

Bearer hospital token

Query Parameters

page(integer)

Page number (default: 1)

limit(integer)

Records per page (default: 20, max: 100)

q(string)

Search patient_name or doctor_name

status(string)

Filter by status (BOOKED, COMPLETED, NO_SHOW, CANCELLED)

patient_id(uuid)

Filter by patient

doctor_id(uuid)

Filter by doctor

branch_id(uuid)

Filter by branch

Response

{
  "success": true,
  "data": {
    "total": 12,
    "results": [
      {
        "id": "appointment-uuid",
        "patient_id": "patient-uuid",
        "patient_name": "Ravi Kumar",
        "doctor_id": "doctor-uuid",
        "doctor_name": "Dr. Priya Rao",
        "appointment_time": "2026-04-15T09:30:00+05:30",
        "status": "BOOKED",
        "branch_id": "branch-uuid",
        "type": "CONSULTATION",
        "created_at": "2026-04-07T12:00:00+05:30"
      }
    ],
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}
PUThttps://server.nyraai.io/api/external/appointments/:id/status

Update the status of an appointment. Only COMPLETED, NO_SHOW, and CANCELLED are accepted (not BOOKED).

Permission: appointments:write

Headers

x-api-keyrequired

API key

x-api-secretrequired

API secret

Authorizationrequired

Bearer hospital token

Content-Typerequired

application/json

Request Body

{
  "status": "COMPLETED"
}

Response

{
  "success": true,
  "message": "Appointment status updated to COMPLETED"
}

Status values

Listing vs PUT /status

PUT /api/external/appointments/:id/status accepts only COMPLETED, NO_SHOW, and CANCELLED.

Allowed on PUT /status

COMPLETED

Appointment was completed

NO_SHOW

Patient did not attend

CANCELLED

Appointment was cancelled

Other statuses (e.g. on GET filters / records)

BOOKED

Appointment is scheduled (returned/filterable on list; not set via this PUT)

Usage Examples

Create Appointment

curl -X POST "https://server.nyraai.io/api/external/appointments" \
  -H "x-api-key: nyra_..." \
  -H "x-api-secret: secret..." \
  -H "Authorization: Bearer token..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "patient-uuid",
    "doctor_id": "doctor-uuid",
    "appointment_date": "2026-04-15",
    "appointment_time": "10:00:00",
    "type": "CONSULTATION"
  }'

List Appointments

curl -X GET "https://server.nyraai.io/api/external/appointments?status=BOOKED&page=1&limit=20" \
  -H "x-api-key: nyra_..." \
  -H "x-api-secret: secret..." \
  -H "Authorization: Bearer token..."

Update Appointment Status

curl -X PUT "https://server.nyraai.io/api/external/appointments/appointment-uuid/status" \
  -H "x-api-key: nyra_..." \
  -H "x-api-secret: secret..." \
  -H "Authorization: Bearer token..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "COMPLETED"
  }'

JavaScript/Node.js Example

const scheduleAppointment = async (appointmentData) => {
  const response = await fetch(
    'https://server.nyraai.io/api/external/appointments',
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.API_KEY,
        'x-api-secret': process.env.API_SECRET,
        'Authorization': `Bearer ${process.env.API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(appointmentData)
    }
  );

  const data = await response.json();
  return data.data.appointment_id;
};

Appointment Fields Reference

patient_iduuid

Patient UUID (or use phone/name)

doctor_iduuid

Doctor UUID

appointment_datedate

Date in YYYY-MM-DD format

appointment_timetime

Time in HH:MM:SS format

typestring

CONSULTATION, FOLLOW_UP, etc.

notesstring

Optional appointment notes

branch_iduuid

Hospital branch UUID