EnrollConnect
Preview. This guide covers an API that is in active development. Content is subject to change.
Integration Overview
┌──────────-────┐ ┌─────────────────┐ ┌─────────────────┐
│ 1. Quote │────▶│ 2. Check plan │────▶│ 3. Enroll via │
│ POST /quotes │ │ enrollment │ │ deeplink or API │
│ │ │ flags │ │ │
└──────────-────┘ └─────────────────┘ └─────────────────┘Step 1: Quote
Use the Quoting API to retrieve plans. Pass off_ex: true for off-exchange plans.
Step 2: Check Enrollment Flags
Each plan will include:
{
"hios_id": "12345AB6780001",
"deeplink_enrollment": true,
"api_enrollment": true
}Route accordingly:
api_enrollment: true: use EnrollConnectdeeplink_enrollment: true: use Application DeeplinkBoth
true: your choice
Step 3: Enroll
Both EnrollConnect and the expanded Application Deeplink accept the same canonical request schema. Build your payload once and send it to either path. See Choosing an Enrollment Path for a detailed comparison.
Follow the appropriate path below.
EnrollConnect: Step by Step
1. Create Application
To start we will require a complete set of fields required to submit the application. We will return validation errors indicating what is missing if not. In the near future, we will be able to support partial applications and filling in remaining fields via update.
external_id is an optional field on the application and on each applicant/dependent. Use it to store your platform's identifier (e.g., enrollment ID, member ID) so you can correlate HealthSherpa records back to your system.
Within a single application, each applicant's external_id must be unique, you cannot assign the same value to the primary and a dependent. Application-level and applicant-level external_id values are separate scopes and don't conflict with each other. There is no cross-application uniqueness constraint: the same external_id may be reused across different applications.
Response includes:
application_id: HealthSherpa application ID (e.g.HSA000000001)payment_instructions: how payment works for this carriererrors: what's still needed before submission
2. Update Application (optional)
Send the complete payload (not a partial diff). Only works while in draft.
The response includes updated errors so you always know what's remaining.
3. Check Validation Errors
Every response includes errors. When the array is empty, the application is ready to submit:
If there are outstanding issues:
Fast follow. Some carriers require payment before submission. When the PUT /payment_method endpoint is available, the errors array will include an error if payment is required but not yet set. Until then, payment is handled outside the API (e.g., via the HealthSherpa UI or carrier redirect). See Upcoming Capabilities for details.
4. Handle Payment (if required)
Check payment_instructions in the application response:
Payment redirect (most carriers). When payment_redirect_supported is true, call GET /api/v1/applications/:id/payment_redirect after submission. The response provides:
endpoint: the carrier's payment URLmethod: alwaysPOSTfields: list of{name, value}pairs to include as hidden form inputs
Your platform builds a form POST to the returned endpoint with the returned fields and submits it in the user's browser. The fields will vary depending on the carrier's payment integration. Include every returned field exactly as provided; do not filter, rename, or modify any entries.
In-flow payment (Cigna, Elevance). When payment_required_with_submission is true, call PUT /api/v1/applications/:id/payment_method before submitting. Supports both bank accounts and credit cards.
Payment information is managed exclusively through the dedicated PUT /payment_method endpoint, not through the application create or update request body. This keeps sensitive data on a separate, PCI-scoped route.
The GET /applications/:id response includes a payment object with carrier-reported payment data (status, paid-through date, balance due, autopay indicator) when available. For carriers that use payment redirect, this data depends on the carrier reporting it back and may not be immediately available after submission.
Fast follow. The PUT /payment_method endpoint is planned as a fast-follow addition. When available, sensitive payment fields (card numbers, CVV, routing and account numbers) must be sent through a PCI-compliant proxy URL provided by HealthSherpa, which tokenizes the data in transit. Details will be provided when this capability is ready.
5. Upload SEP Documents (if applicable)
Most SEP reasons require documentation. Supports both multipart/form-data (direct file upload) and application/json (base64-encoded). See Carrier-Specific SEP Info for per-carrier requirements.
6. Submit
The application transitions to pending_effectuation and becomes read-only. Submission will fail with 422 if errors is not empty.
7. Track Status
Poll for updates:
Or check all recent changes:
The list endpoint is a stretch for the initial launch. At launch, use GET /applications/:id to poll individual applications or rely on webhooks for status updates. The list endpoint will be available shortly after launch.
Status lifecycle:
Using next_actions
Every response includes a next_actions array that tells your platform exactly what operations are available for the application in its current state. Use rel to identify the action, href for the URL, and method for the HTTP verb.
The array is state-aware — after submission, update and submit are replaced with cancel. After effectuation, terminate becomes available. Build your UI off the rel values rather than hardcoding endpoints.
To check if an application is ready to submit, verify that errors is empty. The errors array uses distinct codes (e.g., supporting_documentation_required, payment_required) for submission prerequisites, so no separate readiness check is needed.
If you are subscribed to Webhooks, you will also receive push notifications for submission confirmation and policy status changes. No additional webhook setup required.
Webhook Delivery
Webhooks are delivered at least once. Your endpoint should be idempotent (handle duplicate deliveries gracefully). Delivery details:
Retries
Up to 3 retries at increasing intervals (20 seconds, 10 minutes, 1 hour)
Replay
Contact your account manager to replay missed events for a specific time range
If all retries fail, the event is logged and can be replayed on request.
Effective Dates
The desired_effective_date field in your request is a preference. The actual effective_date is determined by a combination of:
The carrier's effective date rules
The SEP event date and type
State-specific deadlines (e.g., 15th-of-month cutoffs)
OEP windows when applicable
The response always includes both fields. If they differ, effective_date is what the carrier will use. During OEP, most carriers follow standard monthly effective date cycles. During SEP, the effective date is typically the first of the month following the qualifying event, but this varies by carrier and state.
Always use effective_date from the response for downstream logic (e.g., communicating coverage start to employees). Do not assume desired_effective_date will be honored.
Post-Submission Actions
Cancel
POST /applications/:id/cancel
Before effectuation
Terminate
POST /applications/:id/terminate
After effectuation, requires termination_date
Payment redirect
GET /applications/:id/payment_redirect
When payment_redirect_supported is true
Cancel
Cancels an application that is pending effectuation. No request body required. The application transitions to cancelled and a status webhook fires.
If the effective date has already passed and cancellation is not allowed, the cancel request will fail with 422. In that case, use terminate instead.
Terminate
Terminates an effectuated policy. Requires a termination_date in the request body:
Carrier-specific rules apply to termination timing. Most carriers require at least 14 days notice. Most restrict termination to end-of-month dates. If the requested date is not allowed, the API returns 422 with a descriptive error.
Error Handling
All error responses return a top-level errors array. Each entry contains a machine-readable code, a human-readable message, and an optional field dot-path when the error is tied to a specific request field.
Carrier-Specific Validation
The errors array is not a static checklist. Validation rules are applied dynamically based on the selected plan's carrier. For example:
Most carriers require SSN before submission. Some accept ITIN as an alternative.
Guardian information is required for applicants under 18.
Some carriers require specific attestation fields that others do not.
You do not need to know these rules in advance. The errors array will always tell you exactly what is missing or invalid for the specific carrier. Resolve all errors before calling submit.
code
Yes
Machine-readable enum. Switch on this value rather than parsing message strings
message
Yes
Human-readable description. May change over time
field
No
Dot-path to the offending request field. Omitted for auth and system errors
Error Codes
unauthorized
Auth
Missing or invalid API key
forbidden
Auth
API key not linked to agent
not_found
Resource
Application not found
plan_not_found
Resource
Plan HIOS ID not found or not enrollable for the given year
plan_not_available
Validation
Plan exists but is not eligible (wrong carrier, state, or age limit)
missing_required_field
Validation
Required field is blank or null
invalid_field_value
Validation
Value is not in the allowed set (enum, boolean, inclusion)
invalid_field_format
Validation
Format is wrong (SSN, phone, email, date, zip code)
internal_error
System
Unhandled server error
HTTP Status Codes
200
Success
201
Created
400
Malformed request
Fix payload
401
Invalid API key
Check x-api-key header
404
Not found
Verify application ID
422
Validation error
Check errors array
429
Rate limit exceeded
Back off and retry after retry_after seconds
502/503
Upstream error
Retry after a few seconds
Idempotency and Retries
POST /applications includes internal duplicate suppression based on payload hashing within a short retry window. If a network error causes a retry, the duplicate request is suppressed and the original result is returned.
For PUT and action endpoints (submit, cancel, terminate), requests are naturally idempotent: repeating the same call produces the same result.
Include external_id on the application and each applicant for reliable correlation between your system and HealthSherpa. On PUT, match applicants by the HealthSherpa id returned on create — not by external_id.
Rate Limits
Per authenticated API key
50 requests per minute
When a limit is reached, the API returns 429 Too Many Requests with a JSON body:
Back off and retry after the number of seconds indicated in retry_after. During OEP, contact your account manager if you anticipate higher throughput needs.
Testing in Staging
Create application
Returns 201 with id and errors
Update application
Returns 200 with updated errors
Check readiness
errors is empty
Submit
Returns submitted status
Poll status
Status transitions appear
Payment
Handle payment redirect (and in-flow payments, when available)
Never use real PHI/PII in staging. Use synthetic names, dates, and SSNs for all testing.
Go-Live Checklist
Attestations and Compliance
The application schema includes attestation fields such as electronic_signature_consent, agrees_issuer_attestations, and broker_signature_attestation. These are not just data fields. They represent regulatory consent that your platform is responsible for collecting from the consumer.
Your platform must:
Present the relevant disclosure language to the consumer before setting attestation fields to
trueRecord the timestamp of consent (
signatures.signature_date)Ensure the
agent_of_recordnamed in the application is licensed and appointed for the carrier in the application's state
Setting attestation fields to true without presenting the disclosures to the consumer creates compliance risk. HealthSherpa may audit attestation patterns and reserves the right to reject applications where consent flows appear to be bypassed.
Enum References
The following fields use enumerated values. Invalid values will return invalid_field_value errors.
gender
male, female
race_ethnicity
american_indian_or_alaskan_native, asian_indian, black_or_african_american, chinese, filipino, guamanian_or_chamorro, japanese, korean, native_hawaiian, samoan, vietnamese, white, asian_race_not_listed, pacific_islander_race_not_listed, decline_to_answer
hispanic_origin
true, false, decline_to_answer
hispanic_origin_description
cuban, mexican_mexican_american_or_chicanx, puerto_rican, other_hispanic_latino_or_spanish_origin (only when hispanic_origin is true)
language_spoken, language_written
english, spanish, arabic, chinese, french_creole, french, german, gujarati, hindi, korean, polish, portuguese, russian, tagalog, urdu, vietnamese, italian
existing_coverage.type
issuer, government
relationship (dependents)
spouse, domestic_partner, child, stepchild, foster_child, adopted_child, parent, stepparent, parent_in_law, sibling, other
special_enrollment_period.event_type
See Carrier-Specific SEP Info for the full list per carrier
pediatric_dental
purchased_separately, not_applicable
Upcoming Capabilities (Fast Follow)
The following items are planned after the initial EnrollConnect launch:
Enrollment requirements on plan lookup
GET /plans/:hios_id?plan_year=&include=enrollment_information will return enrollment_requirements and attestation_content objects listing required fields, conditionally required fields (with conditions), payment/SEP metadata, and legal attestation text for the selected plan's carrier. The include=enrollment_information flag is opt-in — without it, the endpoint returns standard plan data only. Lets your platform pre-validate data completeness and build legally valid consent screens before making any enrollment API calls.
Partial Applications
Ability to create an application without sending the full required payload. Initially, POST and PUT will require the complete required request body.
GET /applications
Ability to list applications and filter on a variety of fields
PUT /payment_method
Dedicated payment endpoint, enabling support for carriers that require payment in the application flow.
These will be documented as they become available. Contact your account manager for timeline updates.
Last updated