Making Requests

Request Format

All API requests to SaludYa follow REST principles and return JSON responses.

Base URL

https://api.saludya.com/v1

For local development:

http://localhost:3000/v1

Headers

Include these headers in all requests:

Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN

Get your JWT token by authenticating through the /auth/login endpoint. See the Authentication guide for details.

Basic Request Example

Here’s a simple request to fetch appointments:

const response = await fetch('https://api.saludya.com/v1/appointments', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  }
});

const data = await response.json();
console.log(data);

Pagination

List endpoints return paginated results to improve performance. Use the page and limit query parameters to control pagination.

Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number to retrieve
`limit`	integer	20	Number of items per page (max: 100)

Example Request

GET /v1/appointments?page=2&limit=50

const fetchAppointments = async (page = 1, limit = 20) => {
  const url = new URL('https://api.saludya.com/v1/appointments');
  url.searchParams.set('page', page);
  url.searchParams.set('limit', limit);

  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  return response.json();
};

// Fetch page 2 with 50 items
const data = await fetchAppointments(2, 50);

Response Format

Paginated responses include metadata about the result set:

{
  "data": [
    {
      "id": "apt_1234567890",
      "patientId": "pat_9876543210",
      "doctorId": "doc_5555555555",
      "dateTime": "2026-03-15T14:30:00Z",
      "status": "scheduled",
      "reason": "Annual checkup"
    }
    // ... more appointments
  ],
  "pagination": {
    "page": 2,
    "limit": 50,
    "totalPages": 5,
    "totalItems": 243,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

Use the hasNextPage and hasPreviousPage fields to implement navigation in your UI.

Filtering

Filter results using query parameters. Available filters depend on the resource type.

Common Filters

Appointments

GET /v1/appointments?status=scheduled&doctorId=doc_123&date=2026-03-15

Filter	Type	Description
`status`	string	Filter by appointment status (`scheduled`, `completed`, `cancelled`, `no_show`)
`patientId`	string	Filter by patient ID
`doctorId`	string	Filter by doctor ID
`date`	string	Filter by appointment date (ISO 8601 format)
`dateFrom`	string	Appointments starting from this date
`dateTo`	string	Appointments up to this date

Patients

GET /v1/patients?bloodType=O+&insuranceProvider=HealthCare Inc

Filter	Type	Description
`bloodType`	string	Filter by blood type
`insuranceProvider`	string	Filter by insurance provider
`minAge`	integer	Minimum age
`maxAge`	integer	Maximum age

Doctors

GET /v1/doctors?specialization=Cardiology&available=true

Filter	Type	Description
`specialization`	string	Filter by medical specialization
`available`	boolean	Filter by current availability
`rating`	number	Minimum rating (0-5)

Example: Complex Filtering

Find all scheduled appointments for a specific doctor in March 2026:

const fetchDoctorAppointments = async (doctorId, dateFrom, dateTo) => {
  const url = new URL('https://api.saludya.com/v1/appointments');
  url.searchParams.set('doctorId', doctorId);
  url.searchParams.set('status', 'scheduled');
  url.searchParams.set('dateFrom', dateFrom);
  url.searchParams.set('dateTo', dateTo);
  url.searchParams.set('limit', 100);

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  return response.json();
};

const appointments = await fetchDoctorAppointments(
  'doc_123',
  '2026-03-01',
  '2026-03-31'
);

When filtering by date ranges, ensure dates are in ISO 8601 format (YYYY-MM-DD). Invalid date formats will return a 400 error.

Sorting

Sort results using the sortBy and order query parameters.

Parameters

Parameter	Type	Default	Description
`sortBy`	string	`createdAt`	Field to sort by
`order`	string	`desc`	Sort order: `asc` or `desc`

Sortable Fields

Appointments

dateTime - Appointment date and time
createdAt - Record creation date
updatedAt - Last update date
status - Appointment status

Patients

lastName - Patient last name
createdAt - Registration date
dateOfBirth - Date of birth

Doctors

lastName - Doctor last name
specialization - Medical specialization
rating - Average rating
yearsOfExperience - Experience in years

Example Requests

Sort appointments by date (oldest first):

GET /v1/appointments?sortBy=dateTime&order=asc

Sort doctors by rating (highest first):

GET /v1/doctors?sortBy=rating&order=desc

// Fetch upcoming appointments sorted by date
const fetchUpcomingAppointments = async () => {
  const url = new URL('https://api.saludya.com/v1/appointments');
  url.searchParams.set('status', 'scheduled');
  url.searchParams.set('sortBy', 'dateTime');
  url.searchParams.set('order', 'asc');
  url.searchParams.set('dateFrom', new Date().toISOString().split('T')[0]);

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  return response.json();
};

Combining Parameters

You can combine pagination, filtering, and sorting in a single request:

GET /v1/appointments?status=scheduled&doctorId=doc_123&dateFrom=2026-03-15&sortBy=dateTime&order=asc&page=1&limit=25

const fetchFilteredAppointments = async (filters) => {
  const url = new URL('https://api.saludya.com/v1/appointments');
  
  // Add all filter parameters
  Object.entries(filters).forEach(([key, value]) => {
    if (value !== null && value !== undefined) {
      url.searchParams.set(key, value);
    }
  });

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  return response.json();
};

// Usage
const appointments = await fetchFilteredAppointments({
  status: 'scheduled',
  doctorId: 'doc_123',
  dateFrom: '2026-03-15',
  sortBy: 'dateTime',
  order: 'asc',
  page: 1,
  limit: 25
});

Response Status Codes

SaludYa API uses standard HTTP status codes:

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Error Handling

Errors return a consistent JSON format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid date format for 'dateFrom' parameter",
    "field": "dateFrom",
    "details": "Expected ISO 8601 format (YYYY-MM-DD)"
  }
}

try {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }
  
  const data = await response.json();
  return data;
} catch (error) {
  console.error('API Error:', error.message);
  // Handle error appropriately
}

Best Practices

Use Pagination

Always paginate large result sets. Don’t request more than 100 items per page.

Filter Strategically

Apply filters to reduce payload size and improve response times.

Cache Responses

Cache frequently accessed data to reduce API calls and improve performance.

Handle Errors

Implement proper error handling for all API calls.

When building search functionality, combine filters with pagination and sorting to create a powerful user experience.

Next Steps

Rate Limits

Learn about rate limiting and best practices

API Reference

Explore detailed endpoint documentation

Authentication

Learn about authentication methods

Error Handling

Understand error codes and responses

Get Started

Core Concepts

Guides

Request Format

Base URL

Headers

Basic Request Example

Parameters

Example Request

Response Format

Filtering

Common Filters

Appointments

Patients

Doctors

Example: Complex Filtering

Sorting

Parameters

Sortable Fields

Appointments

Patients

Doctors

Example Requests

Combining Parameters

Response Status Codes

Error Handling

Best Practices

Use Pagination

Filter Strategically

Cache Responses

Handle Errors

Next Steps

Rate Limits

API Reference

Authentication

Error Handling

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Request Format

​Base URL

​Headers

​Basic Request Example

​Pagination

​Parameters

​Example Request

​Response Format

​Filtering

​Common Filters

​Appointments

​Patients

​Doctors

​Example: Complex Filtering

​Sorting

​Parameters

​Sortable Fields

​Appointments

​Patients

​Doctors

​Example Requests

​Combining Parameters

​Response Status Codes

​Error Handling

​Best Practices

Use Pagination

Filter Strategically

Cache Responses

Handle Errors

​Next Steps

Rate Limits

API Reference

Authentication

Error Handling

Build docs developers (and LLMs) love

Request Format

Base URL

Headers

Basic Request Example

Pagination

Parameters

Example Request

Response Format

Filtering

Common Filters

Appointments

Patients

Doctors

Example: Complex Filtering

Sorting

Parameters

Sortable Fields

Appointments

Patients

Doctors

Example Requests

Combining Parameters

Response Status Codes

Error Handling

Best Practices

Next Steps