Patients API

Manage patient records. Create, retrieve, and update patient information and history.

GET/v1/patients

Returns a paginated list of patients. Supports full-text search across name, phone, and email.

Query Parameters

Parameter	Type	Required	Description
search	string	Optional	Search by name, phone, or email
page	integer	Optional	Page number (default: 1)
limit	integer	Optional	Results per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.relaya.one/v1/patients?search=sharma" \
  -H "Authorization: Bearer rlya_live_abc123"

Example Response

{
  "data": [
    {
      "id": "pat_4jn7h2",
      "name": "Priya Sharma",
      "phone": "+919876543210",
      "email": "priya.sharma@email.com",
      "dob": "1990-03-15",
      "gender": "female",
      "created_at": "2026-01-10T08:00:00Z",
      "last_visit": "2026-07-20T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "has_more": false
  }
}

POST/v1/patients

Request Body

Parameter	Type	Required	Description
name	string	Required	Full name
phone	string	Required	Phone number (E.164 format)
email	string	Optional	Email address
dob	string	Optional	Date of birth (YYYY-MM-DD)
gender	string	Optional	Gender: male, female, other
address	string	Optional	Mailing address
notes	string	Optional	Internal notes

Example Request

curl -X POST "https://api.relaya.one/v1/patients" \
  -H "Authorization: Bearer rlya_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rahul Verma",
    "phone": "+919812345678",
    "email": "rahul.verma@email.com",
    "dob": "1985-08-22",
    "gender": "male"
  }'

GET/v1/patients/:id

Retrieve a patient by ID, including their appointment history and recent visits.

Example Response

{
  "data": {
    "id": "pat_4jn7h2",
    "name": "Priya Sharma",
    "phone": "+919876543210",
    "email": "priya.sharma@email.com",
    "dob": "1990-03-15",
    "gender": "female",
    "address": "42 MG Road, Bengaluru",
    "created_at": "2026-01-10T08:00:00Z",
    "last_visit": "2026-07-20T10:30:00Z",
    "appointments": [
      {
        "id": "apt_8xk2m9v3",
        "datetime": "2026-07-20T10:30:00Z",
        "doctor_id": "doc_9km3p1",
        "status": "completed"
      }
    ],
    "stats": {
      "total_appointments": 12,
      "completed": 10,
      "cancelled": 2,
      "no_shows": 0
    }
  }
}

PATCH/v1/patients/:id

Update patient information. Only provided fields are modified.

Request Body

Parameter	Type	Required	Description
name	string	Optional	Updated full name
phone	string	Optional	Updated phone (E.164 format)
email	string	Optional	Updated email
address	string	Optional	Updated address
notes	string	Optional	Updated internal notes

Error Codes

Code	Status	Description
400	bad_request	Invalid parameters or malformed phone number
401	unauthorized	Invalid or missing API key
404	not_found	Patient not found
409	conflict	Phone number already registered
429	rate_limited	Too many requests