Skip to content

Expanding Related Entities

The $expand OData query option lets you include related entities inline in a single response, eliminating the need for multiple round-trip requests.

Basic Syntax

GET /Patients?$expand=Appointments

This returns each patient with their related appointments embedded in the response.

Example

Request

curl -X GET "https://api.nymblqa.com/Patients(12345)?$expand=Appointments" \
  -H "Authorization: Bearer eyJraWQiOiJ..." \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "@odata.context": "https://api.nymblqa.com/$metadata#Patients/$entity",
  "id": "12345",
  "first_name": "Jane",
  "last_name": "Doe",
  "Appointments": [
    {
      "id": "appt-001",
      "appointment_date": "2026-03-01",
      "status": "Scheduled",
      "appointment_type_id": "type-123"
    }
  ]
}

Expanding Multiple Relations

Separate multiple expand targets with a comma:

GET /Patients?$expand=Appointments,Physicians

Nested Expand Options

Use parentheses to apply query options within an expanded collection:

GET /Patients?$expand=Appointments($filter=status eq 'Scheduled';$orderby=appointment_date asc;$top=5)

This expands appointments, but only those that are scheduled, sorted by date, limited to 5.

Combining with Other Query Options

$expand works alongside other OData parameters:

GET /Patients?$filter=active eq true&$select=id,first_name,last_name&$expand=Appointments($top=3)

Available Expansions

Entity Expandable Relations
Patients Appointments
Appointments AppointmentTypes, Physicians

Expand Depth Limit

Nested expansions are supported up to 3 levels deep. Requests exceeding this limit will return a 400 Bad Request response.

Best Practices

Tip

  • Only expand relations you actually need — unnecessary expansions increase response size and latency
  • Use $select inside $expand to limit which fields are returned for related entities
  • For large datasets, prefer fetching related entities separately using filtered queries rather than expanding on a large collection