GET

/v1/ping

Live View in OpenAPI

Check that HealthSherpa One is reachable and that your API key is active before making county lookup or quote requests.

Full URL /v1/ping
Request

Send the same x-api-key header you use for other API calls. A successful response means the service accepted the request and recognized your key.

Sample request
request.http 
GET /v1/ping
x-api-key: YOUR_API_KEY
Response
200 response.json 
{
  "environment": "production",
  "ok": true
}
What the status means
200
The service is up and your key was accepted.
403 forbidden
API Gateway rejected the key as missing, invalid, not active yet, or not authorized for this API, or the request was blocked by an API edge policy.
429 rate_limited
Too many requests were sent in a short period. Slow down and retry.
POST

/v1/quotes

Live View in OpenAPI

Return plan quote results for one coverage type at a time. Look up the county first, then send the market, location, and household details needed to calculate plan pricing.

Full URL /v1/quotes
Request body

Use this structure to describe what the agent is quoting: the market, the county, and the household members. The logged-in portal uses the same shape for its prefilled medical example.

Field Use
context Required. Product, exchange, coverage, and plan-year details.
location Required. ZIP, county FIPS, and state when supplied.
household Required. Applicants and applicant screening flags.
household.applicants[].member_id Required. Caller-supplied applicant identifier. Use a stable non-empty string from your system, such as applicant-1; send relationship separately.
household.applicants[] required fields member_id, age, relationship, and uses_tobacco.
annual_income
effective_date		 Optional for quote-only requests.
filters
sort
page		 Optional controls for filtering, ordering, and pagination.
include Deprecated and ignored. Quotes always return the canonical payload and add a deprecation message to meta.warnings when include is supplied.
Allowed values

These values are checked before the quote is processed. Invalid values return a 400 invalid_request response with field-level details.

context.product
Allowed
aca, ichra
Notes
aca is the current portal example. ichra uses the same request shape.
context.exchange
Allowed
on_exchange, off_exchange
Rule
Exchange scope is singular per request. Do not send a combined market value.
context.coverage_family + context.coverage_type
medical
medical
ancillary
dental, vision, supplemental_other
Rule
The controller validates that coverage_type matches the selected coverage_family.
context.plan_year
Range
Integer greater than or equal to 2020
Default
Uses the current published plan year when omitted.
location.zip_code + location.fips_code
Format
Both fields must be exactly five digits.
Lookup
Use GET /v1/reference/counties to resolve the county FIPS code before quoting.
location.state
Allowed
Optional two-letter quoteable state code for one of the 50 states or DC.
Rule
When present, it must match the leading state digits in fips_code.
household.applicants[].relationship
Allowed
primary, spouse, dependent
household.applicants[].gender
Optional
Only send this when your quote flow needs applicant gender for marketplace screening.
Allowed
female, male, other, unknown
household.applicants[].uses_tobacco and screening flags
Boolean
true or false
Rule
uses_tobacco is required for each applicant. pregnant, blind_or_disabled, and native_american are optional booleans.
filters.medical.metal_levels[]
Allowed
bronze, expanded_bronze, silver, gold, platinum, catastrophic
Scope
Medical-only filter. Invalid values are rejected by the request model.
filters.medical.plan_types[]
Allowed
hmo, ppo, epo, pos, indemnity
Scope
Medical-only filter. Invalid values are rejected by the request model.
sort.direction
Allowed
asc, desc
sort.field
medical
premium, deductible, moop
dental
premium, deductible, moop, annual_maximum
vision
premium, exam_copay, frames_allowance
supplemental_other
premium, issue_age_max
page.number + page.size
Default
page.number defaults to 1. page.size defaults to 20.
Limit
page.size is capped at 500.
Sample request
request.http 
POST /v1/quotes
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "context": {
    "product": "aca",
    "exchange": "on_exchange",
    "coverage_family": "medical",
    "coverage_type": "medical",
    "plan_year": 2026
  },
  "location": {
    "zip_code": "30301",
    "fips_code": "13121",
    "state": "GA"
  },
  "household": {
    "household_size": 1,
    "applicants": [
      {
        "member_id": "applicant-1",
        "age": 30,
        "date_of_birth": "1996-05-01",
        "relationship": "primary",
        "uses_tobacco": false,
        "pregnant": false,
        "blind_or_disabled": false,
        "native_american": false
      }
    ],
    "annual_income": 50000,
    "effective_date": "2026-05-01"
  },
  "sort": {
    "field": "premium",
    "direction": "asc"
  },
  "page": {
    "number": 1,
    "size": 20
  }
}
Response
Field Use
plans[] Homogeneous for the requested coverage_type.
Plan data Identifiers, issuer, network, pricing, documents, availability, subtype-specific details, and release metadata.
api_enrollable true means the quoted plan can be used with the direct off-exchange enrollment API at quote time. false means use quote/display only or another enrollment path. This is not consumer ACA eligibility and does not guarantee successful submission after applicant and carrier validation.
meta page_number, page_size, result_count, and warnings.
Sample 200 response
200 response.json 
{
  "plans": [
    {
      "plan_id": "38344AK1060001",
      "variant_id": "01",
      "coverage_family": "medical",
      "coverage_type": "medical",
      "name": "Premera Blue Cross Preferred Gold 1500",
      "api_enrollable": false,
      "context": {
        "product": "aca",
        "exchange": "on_exchange",
        "coverage_family": "medical",
        "coverage_type": "medical",
        "plan_year": 2026
      },
      "issuer": {
        "issuer_id": "38344",
        "name": "Premera Blue Cross Blue Shield of Alaska",
        "state": "AK"
      },
      "pricing": {
        "gross_premium": 844.15,
        "ehb_premium": 843.39,
        "subsidy_applied": 0.0,
        "net_premium": 844.15,
        "currency": "USD",
        "billing_period": "monthly"
      },
      "documents": {
        "sbc_url": "https://example.com/sbc.pdf",
        "formulary_url": "https://example.com/formulary"
      },
      "availability": {
        "service_area_id": "AKS001",
        "rating_area": "1",
        "state": "AK"
      },
      "details": {
        "type": "medical",
        "metal_level": "gold",
        "plan_type": "ppo",
        "hsa_eligible": false,
        "deductible_individual": 1500,
        "deductible_family": 3000,
        "moop_individual": 9200,
        "moop_family": 18400,
        "csr_level": "none"
      },
      "release": {
        "release_id": "2026-public-release",
        "plan_year": 2026
      }
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "result_count": 1,
    "warnings": []
  }
}
When errors happen
200
Returns matching plans. If no plans match, the response is still 200 with an empty plans[] array and meta.result_count: 0.
400 invalid_request
The request is missing required fields, uses the wrong JSON type, has an invalid ZIP or FIPS code, or includes values that do not match the allowed options.
403 forbidden
API Gateway rejected the key as missing, invalid, not active yet, or not authorized for this API, or the request was blocked by an API edge policy.
429 rate_limited
Too many quote requests were sent in a short period. Slow down and retry.
503 service_unavailable
A plan data, catalog, or marketplace dependency could not complete the quote request.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
Sample error response
400 error.json 
{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed.",
    "details": {
      "context.product": [
        "Product is not included in the list"
      ],
      "location.zip_code": [
        "ZIP code must be 5 digits"
      ],
      "household.applicants[0].member_id": [
        "Member ID can't be blank"
      ],
      "household.applicants[0].uses_tobacco": [
        "Uses tobacco is required"
      ]
    }
  }
}
GET

/v1/reference/counties

Live View in OpenAPI

Find the county choices for a ZIP code before quoting. If a ZIP crosses county lines, show the choices to the agent and send the selected fips_code in POST /v1/quotes.

Full URL /v1/reference/counties
Request

Send one required zip_code query parameter. HealthSherpa checks its ZIP-to-county data first and falls back to the CMS Marketplace lookup when needed.

Field Use
zip_code Required five-digit query parameter.
fips_code Returned county choice to carry into the quote request.
Sample request
request.http 
GET /v1/reference/counties?zip_code=42223
x-api-key: YOUR_API_KEY
Response

The public response returns only the fields you need for the next step: county name, county fips_code, and state.

200 response.json 
{
  "counties": [
    {
      "fips_code": "21047",
      "name": "Christian County",
      "state": "KY"
    },
    {
      "fips_code": "47125",
      "name": "Montgomery County",
      "state": "TN"
    }
  ]
}
When errors happen
200
Returns one or more county choices for the ZIP.
400 invalid_request
zip_code is missing or is not a five-digit ZIP code.
403 forbidden
API Gateway rejected the key as missing, invalid, not active yet, or not authorized for this API, or the request was blocked by an API edge policy.
404 not_found
No county data was found for that ZIP code.
429 rate_limited
Too many lookup requests were sent in a short period. Slow down and retry.
503 service_unavailable
The fallback county lookup could not complete the request.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
Sample error response
404 error.json 
{
  "error": {
    "code": "not_found",
    "message": "No counties found for ZIP 12345."
  }
}
GET

/v1/reference/issuers

Live View in OpenAPI

List the QHP issuers active in a state for a plan year. Use this to build issuer filters in your shopping UI or to validate that an inbound quote request targets a known HIOS issuer ID.

Full URL /v1/reference/issuers
Request

Send the required state query parameter and an optional plan_year. When plan_year is omitted the response defaults to the current ACA plan year — supply it explicitly during open enrollment rollover or when reconciling a prior-year enrollment.

Field Use
state Required two-letter uppercase US state code (e.g. FL, CA, DC). Lowercase values are rejected with 400 invalid_request.
plan_year Optional integer between 2020 and 2099. Defaults to the current ACA plan year.
hios_issuer_id Returned 5-digit HIOS issuer ID to carry into quote filters or plan lookups.
Sample request
request.http 
GET /v1/reference/issuers?state=FL
x-api-key: YOUR_API_KEY
Response

One entry per HIOS issuer with a sortable display name (issuer marketing name when present, legal name otherwise) and the canonical 5-digit hios_issuer_id. Entries are sorted by name (case-insensitive) and then by hios_issuer_id as a stable tiebreaker, so clients can iterate the array directly without re-sorting.

200 response.json 
{
  "issuers": [
    {
      "name": "Gulf Coast Coverage Co.",
      "hios_issuer_id": "33333"
    },
    {
      "name": "Sunshine State Health",
      "hios_issuer_id": "12345"
    }
  ]
}
When errors happen
200
Returns one or more issuers for the state and plan year.
400 invalid_request
state is missing or is not a US state code, or plan_year is not an integer in 2020..2099.
403 forbidden
API Gateway rejected the key as missing, invalid, not active yet, or not authorized for this API, or the request was blocked by an API edge policy.
404 not_found
No active issuers were found for the state in the requested plan year.
429 rate_limited
Too many requests in a short period. Slow down and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
Sample error response
404 error.json 
{
  "error": {
    "code": "not_found",
    "message": "No issuers found for state FL in plan year 2026."
  }
}
GET

/v1/reference/providers

Live View in OpenAPI

Search healthcare providers (individuals and facilities) by name near a ZIP code. Use the returned 10-digit NPI to reference a provider in later requests. This is a search endpoint, not a full directory listing.

Full URL /v1/reference/providers
Request

Send the required query (provider or facility name), zip_code (five-digit ZIP for the near-ZIP search), and exchange (on_exchange or off_exchange) to choose the marketplace channel. Use the optional nested page[number] and page[size] to page through results (the same page model as quoting).

Field Use
query Required provider or facility name to search for.
zip_code Required five-digit ZIP code used for the geographic (near-ZIP) search.
exchange Required marketplace channel: on_exchange or off_exchange.
page[number] Optional page number (mirrors quoting's page.number). Defaults to 1; values below 1 are treated as 1.
page[size] Optional results per page (mirrors quoting's page.size), from 1 to 50. Defaults to 50; values outside this range resolve to 50.
Sample request
request.http 
GET /v1/reference/providers?query=Smith&zip_code=85001&exchange=on_exchange
x-api-key: YOUR_API_KEY
Response

A providers array for the current page. Each entry includes the 10-digit npi, a display_name, entity_type, specialty, and address fields. Pagination lives in meta (page_number, page_size, result_count), matching the quoting response. A search with no matches returns an empty providers array.

200 response.json 
{
  "providers": [
    {
      "display_name": "John Smith, MD",
      "entity_type": "individual",
      "npi": "1972113918",
      "specialty": "Family Medicine",
      "city": "Phoenix",
      "state": "AZ",
      "zip_code": "85001"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 50,
    "result_count": 1
  }
}
When errors happen
200
Returns provider matches for the current page, or an empty list when nothing matches.
400 invalid_request
query, zip_code, or exchange is missing, or exchange is not on_exchange or off_exchange.
403 forbidden
API Gateway rejected the key as missing, invalid, not active yet, or not authorized for this API, or the request was blocked by an API edge policy.
429 rate_limited
Too many requests in a short period. Slow down and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
503 service_unavailable
Provider search is temporarily unavailable. Retry shortly.
Sample error response
400 error.json 
{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed.",
    "details": {
      "zip_code": [
        "ZIP code is required."
      ]
    }
  }
}
POST

/v1/enrollment-sessions

Approval required View in OpenAPI

Use this endpoint to send the browser to a HealthSherpa enrollment flow for guided shopping, application preparation, and enrollment completion. On-exchange enrollment approval is required for both flows and must be requested in the developer portal before use.

Full URL /v1/enrollment-sessions
Idempotency Optional Idempotency-Key header. Keys are treated as unique within a 24-hour window.
Request body

The context object is required, as is every field inside it. This keeps product, exchange, coverage, plan year, flow, and locale explicit on every request. Callers must also supply at least one of location.state or top-level plan_id. Unsupported fields anywhere in the body are rejected with 400 invalid_request.

Field Use
context Required. Product, exchange, coverage, plan year, flow, and locale.
plan_id Plan ID (HIOS). Supply when not providing location.state.
external_id Strongly recommended. Partner-supplied identifier echoed in the response and forwarded for CRM correlation. Must not contain PII.
location Optional. Accepts zip_code, fips_code, and state. Address-level fields (address, address_2, city) are rejected.
client Optional contact identity (first_name, last_name, email, phone_number).
household Optional household details and applicants. household_size must be positive; applicants can include at most one primary and one spouse.
enrollment.hra Optional HRA funding (amount, frequency). Other enrollment subobjects are rejected.
campaign Optional marketing attribution (UTM, cid, display_phone_number). Only allowed when context.flow is self_service.
Allowed values

These values are checked when the request is validated. Invalid or unsupported values return 400 invalid_request with field-level details.

context.product
Allowed
aca
context.exchange
Allowed
on_exchange
context.coverage_family + context.coverage_type
Allowed
medical (both fields)
context.plan_year
Range
Integer between 2020 and 2099.
context.flow
agent_assisted
Use when an agent is helping the shopper. The agent must sign in to HealthSherpa in the browser before continuing.
self_service
Use when the shopper is completing the flow without an agent sign-in. Approval for On-Exchange Enrollment access is required before using either flow.
context.locale
Allowed
en-US, es-MX
Notes
es-MX renders the enrollment page in Spanish.
location.zip_code + location.fips_code
Format
Both fields must be exactly five digits.
Notes
Use GET /v1/reference/counties to resolve a ZIP to county FIPS codes.
location.state
Allowed
Two-letter US state code (50 states plus DC).
Rule
Required when plan_id is not supplied.
household.household_size
Range
Integer greater than or equal to 1.
household.applicants[].relationship
Allowed
primary, spouse, dependent
Notes
Required on every applicant. A household can include at most one primary and one spouse.
household.applicants[].date_of_birth + household.applicants[].age
Rule
date_of_birth and age are mutually exclusive on the same applicant. date_of_birth must not be in the future.
Range
age is an integer between 0 and 130.
household.applicants[].sex
Allowed
female, male
household.applicants[] screening flags
Boolean
true or false
Fields
uses_tobacco, pregnant, parent_caretaker, rejected_by_medicaid_or_chip, unemployment, has_existing_coverage
household.applicants[].ichra
Fields
offered, offered_cafeteria (booleans), employee_amount, family_amount (numbers >= 0).
enrollment.hra.amount + enrollment.hra.frequency
amount
Required when hra is supplied. Number >= 0. 0 means the consumer declined HRA funding; a positive value means funding was accepted.
frequency
Required when amount > 0. Allowed: annually, monthly, quarterly, one_time.
campaign
Allowed
cid, utm_source, utm_medium, utm_campaign, utm_term, utm_content, display_phone_number
Rule
Only accepted when context.flow is self_service. Sending any field with flow: "agent_assisted" is rejected with 400 invalid_request.
Notes
display_phone_number is rendered in the page header. Must be a 10-digit US phone number (e.g. 8005551234, 800-555-1234, (800) 555-1234); +1-prefixed values are rejected with 400 invalid_request.
Sample request
request.http 
POST /v1/enrollment-sessions
x-api-key: YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 9b1c4f4e-9c2c-4f8f-9a3b-1e2d3a4b5c6d

{
  "external_id": "crm-lead-abc-123",
  "context": {
    "product": "aca",
    "exchange": "on_exchange",
    "coverage_family": "medical",
    "coverage_type": "medical",
    "plan_year": 2026,
    "flow": "agent_assisted",
    "locale": "en-US"
  },
  "client": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone_number": "5551234567"
  },
  "plan_id": "12345NY0010001",
  "location": {
    "zip_code": "10001",
    "fips_code": "36061",
    "state": "NY"
  },
  "household": {
    "annual_income": 42000,
    "household_size": 1,
    "applicants": [
      {
        "relationship": "primary",
        "date_of_birth": "1990-01-01",
        "sex": "female",
        "uses_tobacco": false
      }
    ]
  }
}
Response

Successful responses always return links.shopping_url and links.client_apply_url. The external_id field is echoed from the request when supplied; otherwise it is null.

Field Use
external_id Echoed from the request when supplied; otherwise null.
links.shopping_url HealthSherpa public shop URL (https://healthsherpa.com/public/shop?...).
links.client_apply_url HealthSherpa public apply URL (https://healthsherpa.com/public/apply?...). Always present.
Sample 200 response
200 response.json 
{
  "external_id": "crm-lead-abc-123",
  "links": {
    "shopping_url": "https://healthsherpa.com/public/shop?_agent_id=agent_admin_42&external_id=crm-lead-abc-123&fip_code=36061&household_income=42000&household_size=1&people%5Bprimary%5D%5Bage%5D=36&people%5Bprimary%5D%5Bgender%5D=female&people%5Bprimary%5D%5Btobacco%5D=false&state=NY&user_type=agent&year=2026&zip_code=10001",
    "client_apply_url": "https://healthsherpa.com/public/apply?_agent_id=agent_admin_42&external_id=crm-lead-abc-123&fip_code=36061&household_income=42000&household_size=1&people%5Bprimary%5D%5Bage%5D=36&people%5Bprimary%5D%5Bgender%5D=female&people%5Bprimary%5D%5Btobacco%5D=false&plan_hios_id=12345NY0010001&state=NY&user_type=agent&year=2026&zip_code=10001"
  }
}
When errors happen
200
Enrollment session started successfully. URLs are returned in links.
400 invalid_request
Body validation failed. Common causes: missing required context fields, unsupported field anywhere in the body, neither location.state nor plan_id supplied, both date_of_birth and age on the same applicant, or campaign fields with flow: "agent_assisted".
401 unauthorized
Backend runtime authentication failure when a request reaches a runtime that performs its own authentication.
403 forbidden
The key was rejected at the API edge, or the developer's HealthSherpa Marketplace setup is not in the state the requested flow needs. The check is flow-scoped and both flows require approved on-exchange enrollment access: agent_assisted also requires a healthy HealthSherpa Marketplace link with an active OAuth connection and unexpired or refreshable access token, plus an OAuth-linked agent whose agency is approved for enrollment deeplink URL generation; self_service also requires a configured deeplink agent ID.
413 payload_too_large
The request body exceeded the maximum size accepted by the API edge.
415 unsupported_media_type
The request Content-Type is not supported by the endpoint.
429 rate_limited
Too many requests were sent in a short period. Back off and retry after the delay advertised in the Retry-After header.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
The API edge is failing to reach the backend, or an upstream catalog or lookup service is unavailable.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
Sample error response
400 error.json 
{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed.",
    "details": {
      "zip_code": [
        "ZIP code must be 5 digits"
      ]
    }
  }
}
Approval required

Off-Exchange Enrollment API

View in OpenAPI

Approved partners can create off-exchange enrollment application drafts through the HealthSherpa ONE application contract.

Endpoints
Method Endpoint
POST /v1/enrollmentsCreate a draft off-exchange application. Requires Idempotency-Key.
PUT /v1/enrollments/:idUpdate top-level application sections with required context. Idempotency-Key is not required.
POST /v1/enrollments/:id/supporting_documentationUpload SEP supporting documentation as multipart binary or JSON base64.
GET /v1/enrollments/:idRead the application with required routing context, validation state, payment instructions, policy data, and events when available.
GET /v1/enrollmentsList applications with optional status, id, plan, timestamp, and pagination filters.
POST /v1/enrollments/:id/submissionsSubmit the application to the carrier after readback shows no outstanding errors[].
GET /v1/enrollments/:id/payment_redirectReturn carrier payment redirect data for browser form POST payments.
POST /v1/enrollments/:id/cancellationsCancel an application that is pending effectuation when the carrier supports cancellation.
POST /v1/enrollments/:id/terminationsTerminate an active policy before its natural expiration date when the carrier supports termination.
POST

/v1/enrollments

Request

Create a draft application. Send the application at the request root with context.product = "ichra", context.exchange = "off_exchange", and context.plan_year.

Full URL /v1/enrollments
Idempotency Required Idempotency-Key header.
request.http 
POST /v1/enrollments
x-api-key: YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 9b1c4f4e-9c2c-4f8f-9a3b-1e2d3a4b5c6d

{
  "context": {
    "product": "ichra",
    "exchange": "off_exchange",
    "plan_year": 2026
  },
  "plan_hios_id": "12345FL0010001",
  "applicants": {
    "primary": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1990-01-01",
      "gender": "female"
    }
  },
  "residential_address": {
    "street_address_1": "123 Main St",
    "city": "Miami",
    "state": "FL",
    "zip_code": "33101"
  }
}
When errors happen
400 invalid_request
The body is malformed, routing context is unsupported, or server-owned fields were sent.
400 missing_required_field
Required application fields such as plan_hios_id, applicants.primary, or residential_address are missing.
400 idempotency_key_required
The create request did not include an Idempotency-Key header.
400 idempotency_key_invalid
The supplied Idempotency-Key is malformed.
409 idempotency_in_progress
A retry with the same Idempotency-Key is already in progress.
409 duplicate_external_id
The supplied external_id already belongs to another application.
422 idempotency_mismatch
The same Idempotency-Key was reused with a different body.
422 invalid_field_value
One or more application fields have values the carrier or plan cannot accept.
422 plan_not_available
The selected plan is not available for the requested application details.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
PUT

/v1/enrollments/:id

Request

Update an application with a full replacement-style payload. Include unchanged fields you want to keep, and send the full applicants.primary object when updating primary applicant data.

Full URL /v1/enrollments/{enrollment_id}
Idempotency Idempotency-Key is not required.
request.http 
PUT /v1/enrollments/HSA000000001
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "context": {
    "product": "ichra",
    "exchange": "off_exchange",
    "plan_year": 2026
  },
  "plan_hios_id": "12345FL0010001",
  "applicants": {
    "primary": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1990-01-01",
      "gender": "female"
    }
  },
  "residential_address": {
    "street_address_1": "123 Main St",
    "city": "Miami",
    "state": "FL",
    "zip_code": "33101"
  }
}
When errors happen
400 invalid_request
The body is malformed, required context is missing, unsupported fields were sent, or the application cannot be changed in its current state.
404 not_found
No application was found for the supplied id and approved account.
409 duplicate_external_id
The supplied external_id already belongs to another application.
422 invalid_field_value
The update is not accepted for this application state, carrier, or field value.
422 invalid_field_format
One or more submitted fields use the wrong format.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
POST

/v1/enrollments/:id/supporting_documentation

Request

Upload SEP supporting documentation when readback indicates documents are required. Send a PDF, JPEG, or PNG file as multipart binary or JSON base64.

Full URL /v1/enrollments/{enrollment_id}/supporting_documentation
request.http 
POST /v1/enrollments/HSA000000001/supporting_documentation
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "context": {
    "product": "ichra",
    "exchange": "off_exchange"
  },
  "file": {
    "filename": "sep-proof.pdf",
    "content_type": "application/pdf",
    "content_base64": "JVBERi0xLjQg..."
  },
  "document_type": "sep"
}
When errors happen
400 invalid_request
Required context, document type, or file metadata is missing or invalid.
404 not_found
No application was found for the supplied id and approved account.
413 payload_too_large
The upload is too large.
415 unsupported_media_type
The media type is unsupported.
422 invalid_field_value
The document is not accepted for this application.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
GET

/v1/enrollments/:id

Request

Read one application by id. Send product and exchange as query parameters; do not send plan_year on readback.

Full URL /v1/enrollments/{enrollment_id}
request.http 
GET /v1/enrollments/HSA000000001?product=ichra&exchange=off_exchange
x-api-key: YOUR_API_KEY
When errors happen
400 invalid_request
product or exchange is missing, or unsupported read query parameters such as plan_year or include_events were sent.
404 not_found
No application was found for the supplied id and approved account.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
GET

/v1/enrollments

Request

List applications for your approved account. Use optional status, id, plan, issuer, employer, timestamp, limit, and offset filters.

Full URL /v1/enrollments
request.http 
GET /v1/enrollments?product=ichra&exchange=off_exchange&policy_status=effectuated&limit=25&offset=0
x-api-key: YOUR_API_KEY
When errors happen
400 invalid_request
Required routing values are missing, pagination values are out of range, or unsupported list controls such as include_events were sent.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
POST

/v1/enrollments/:id/submissions

Request

Submit the application after readback shows no outstanding errors[]. Processing can continue asynchronously; poll readback for the final policy status.

Full URL /v1/enrollments/{enrollment_id}/submissions
request.http 
POST /v1/enrollments/HSA000000001/submissions
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "context": {
    "product": "ichra",
    "exchange": "off_exchange"
  }
}
When errors happen
400 invalid_request
Required context is missing or the request is not valid for this application state.
404 not_found
No application was found for the supplied id and approved account.
422 missing_required_field
The application still has required fields to complete before submission.
422 supporting_documentation_required
Supporting documentation must be uploaded before the application can be submitted.
422 invalid_field_value
The request is not valid for this application state, or no changes have been made since the last submission.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
GET

/v1/enrollments/:id/payment_redirect

Request

Retrieve carrier payment redirect data when payment_instructions.payment_redirect_supported is true. Submit every returned field unchanged in the shopper's browser.

Full URL /v1/enrollments/{enrollment_id}/payment_redirect
request.http 
GET /v1/enrollments/HSA000000001/payment_redirect?product=ichra&exchange=off_exchange
x-api-key: YOUR_API_KEY
When errors happen
404 not_found
No application was found for the supplied id and approved account.
422 invalid_field_value
Payment redirect is not supported for this carrier or application.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
POST

/v1/enrollments/:id/cancellations

Request

Cancel a pending-effectuation application when readback shows cancellation is available. If the result is unknown after a timeout, poll readback before retrying.

Full URL /v1/enrollments/{enrollment_id}/cancellations
request.http 
POST /v1/enrollments/HSA000000001/cancellations
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "context": {
    "product": "ichra",
    "exchange": "off_exchange"
  }
}
When errors happen
400 invalid_request
Required routing context is missing or malformed.
400 invalid_field_value
Cancellation is not available for this application or carrier.
404 not_found
No application was found for the supplied id and approved account.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.
POST

/v1/enrollments/:id/terminations

Request

Terminate an active policy when readback shows termination is available. If the result is unknown after a timeout, poll readback before retrying.

Full URL /v1/enrollments/{enrollment_id}/terminations
request.http 
POST /v1/enrollments/HSA000000001/terminations
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "context": {
    "product": "ichra",
    "exchange": "off_exchange"
  }
}
When errors happen
400 invalid_request
Required routing context is missing or malformed.
400 invalid_field_value
Termination is not available for this application or carrier.
404 not_found
No application was found for the supplied id and approved account.
403 forbidden
The key is not authorized for direct enrollment, or an API edge policy denied the request.
429 rate_limited
Too many requests were sent in a short period. Back off and retry.
500 internal_error
Something unexpected happened on the server. Retry later or contact support if it continues.
502 bad_gateway
The API edge received an invalid response from the backend.
503 service_unavailable
A direct enrollment dependency is temporarily unavailable. Retry later.
504 gateway_timeout
The API edge did not receive a timely response from the backend.