First Request

This guide walks through a complete plan search request and explains every part of the response.

Prerequisites

• An Opelyx API key (get one here)
• A tool for making HTTP requests (curl, Python, or any HTTP client)

Making the Request

curl

curl -s -H "Authorization: Bearer op_YOUR_API_KEY_HERE" \
  "https://api.opelyx.com/v1/health/plans?zip=33139&age=35&metal_level=silver" \
  | python3 -m json.tool

Python

import requests

response = requests.get(
    "https://api.opelyx.com/v1/health/plans",
    headers={"Authorization": "Bearer op_YOUR_API_KEY_HERE"},
    params={"zip": "33139", "age": 35, "metal_level": "silver"},
)
response.raise_for_status()
data = response.json()
print(f"Found {data['total']} Silver plans in Miami")

JavaScript

const params = new URLSearchParams({
  zip: "33139",
  age: "35",
  metal_level: "silver",
});

const response = await fetch(
  `https://api.opelyx.com/v1/health/plans?${params}`,
  {
    headers: { Authorization: "Bearer op_YOUR_API_KEY_HERE" },
  },
);

const data = await response.json();
console.log(`Found ${data.total} Silver plans in Miami`);

Understanding the Response

The API returns a HAL-formatted JSON response with these key sections:

Top-Level Fields

Field	Description
_links	Navigation links (self, next page, related resources)
_embedded.plans	Array of matched plan objects
total	Total number of matching plans
page_size	Number of plans per page (default: 20)
state_code	Resolved state for the ZIP code
rating_area_id	CMS rating area for premium calculation

Plan Object Fields

Each plan in _embedded.plans includes:

Field	Description
plan_id	Unique plan identifier (HIOS format)
plan_name	Marketing name of the plan
issuer_name	Insurance company name
metal_level	Bronze, Silver, Gold, Platinum, or Catastrophic
premium	Monthly premium for the requested age
deductible	Annual individual deductible
max_out_of_pocket	Annual individual MOOP
plan_type	HMO, PPO, EPO, or POS
_links.self	Direct link to this plan’s detail endpoint

Response Headers

Every response includes rate limit and caching headers:

Header	Description
X-Request-Id	UUID for tracing and support requests
RateLimit-Limit	Your daily request allowance
RateLimit-Remaining	Requests remaining today
RateLimit-Reset	Unix timestamp when the limit resets
ETag	Weak ETag for conditional requests
Link	RFC 8288 pagination and resource links

Next Steps

• Plan Search Guide — Advanced filters, sorting, and pagination
• Error Handling — RFC 9457 Problem Details format
• API Reference — Complete endpoint documentation