Sign in

v1

latestOpenAPI 3.0.02026-07-231358118.3 KB
Applications

Create application

Creates a new enrollment application in draft state. Payment information is managed separately via PUT /api/v1/applications/{id}/payment_method.

Some carriers enforce eligibility requirements at create time. If an applicant's data matches a disqualifying value (e.g., us_citizen: false), the request returns 422 with code: "ineligible_for_enrollment" and a field path identifying the affected applicant.

post/api/v1/applications

Request body

external_idstring

Your unique identifier for this application.

_agent_idstring nullable

HealthSherpa-provided agent identifier (slug). Optional for API. When provided, the application appears under this agent's book of business in HealthSherpa. When omitted, the agent defaults to the one associated with your platform account. Required for deeplink.

tpa_slugstring

HealthSherpa-assigned TPA identifier (provided during onboarding).

plan_hios_idstring required

14-character HIOS plan ID.

plan_yearinteger required
dental_plan_hios_idstring nullable

HIOS ID of a qualified stand-alone dental plan. Used by HCSC (Blue Cross Blue Shield of IL, MT, NM, OK, TX) plans that require pediatric dental coverage. Provide this or attestations.pediatric_dental — exactly one must be present, not both.

desired_effective_datestring date

Optional. When omitted, the carrier auto-determines the effective date based on the SEP type and event date (recommended). When provided, the date must be one of the carrier's valid effective dates for the given SEP reason and event date. If the date is invalid, the API returns a 422 with either the list of valid dates to choose from, or a message indicating that effective date selection is not available for the given enrollment parameters (meaning the carrier does not allow date selection for this SEP type). There is no endpoint to query valid dates ahead of time.

american_indian_or_alaskan_native_in_householdboolean

Response

Application created

application_idstring
external_idstring
tpa_slugstring
policy_status'draft' | 'pending_effectuation' | 'effectuated' | 'submission_failed' | 'cancelled' | 'terminated'

draft when the application has not yet been submitted. Transitions to pending_effectuation on successful submission. submission_failed when the asynchronous carrier submission failed after the submit endpoint returned 202. Poll the application to detect this state and check errors for details.

document_status'none_needed' | 'required' | 'uploaded' | 'verified' | 'denied' nullable

SEP document verification status. Transitions are driven by carrier responses and document uploads. none_needed: no documentation required for this SEP type. required: documentation required but not yet uploaded. Upload via POST /applications/:id/supporting_documentation. uploaded: documentation uploaded and sent to carrier, pending verification. verified: carrier has verified the documentation. denied: carrier denied the documentation; the application may be suspended.

Status may also change if the carrier initiates a document review after submission (e.g., SEP suspension). Poll the application or subscribe to webhooks to detect transitions.

sep_reasonstring nullable
created_atstring date-time
updated_atstring date-time
submitted_atstring date-time nullable
desired_effective_datestring date
plan_hios_idstring
plan_yearinteger
issuer_hios_idstring
applicationobject

Echo of the application data as stored.

supports_changesboolean

Whether the carrier supports post-enrollment changes for this application. Only present on submitted applications.

can_change_planboolean

Whether a plan change is currently allowed (based on carrier support, OEP/SEP eligibility, and active policy). Only present on submitted applications.

can_report_changeboolean

Whether demographic changes can be reported (based on carrier support and policy expiration). Only present on submitted applications.