# EnrollConnect API EnrollConnect is a full-lifecycle enrollment API that gives partners programmatic control over off-exchange health insurance applications, from creation through carrier submission and status tracking. {% hint style="info" %} Already integrated with the Application Deeplink, Quoting API, or Webhooks? Those continue to work as-is. EnrollConnect is an additional option for partners who need API-level control over the enrollment experience. {% endhint %} Environments:
EnvironmentURL
Staginghttps://api.ichra-staging.healthsherpa.com
Productionhttps://api.ichra.healthsherpa.com
*** #### Application Lifecycle ``` ┌───────────┐ ┌─────────┐ ┌────────┐ ┌───────────┐ │ Create │────>│ Update │────>│ Submit │────>│ Pay │ │ (draft) │ │ (draft) │ │ (send) │ │ (redirect)│ └───────────┘ └─────────┘ └────┬───┘ └─────┬─────┘ │ │ ┌─────────────────────────────────┘ v ┌──────────────────┐ │ Poll for status │ │ or await webhook │ └────────┬─────────┘ │ ┌──────────────┼──────────────┐ v v v ┌───────────┐ ┌──────────┐ ┌────────────┐ │Effectuated│ │ Cancelled│ │ Terminated │ └───────────┘ └──────────┘ └────────────┘ ``` Every response includes an `errors` array. An empty array means the application is ready to submit. *** #### Endpoints
MethodPathDescription
POST/api/v1/applicationsCreate a draft application
PUT/api/v1/applications/:idUpdate a draft application
GET/api/v1/applications/:idRetrieve application details, status, and validation errors
GET/api/v1/applicationsList applications (paginated, filterable)
POST/api/v1/applications/:id/supporting_documentationUpload SEP documents
POST/api/v1/applications/:id/submitSubmit to carrier
POST/api/v1/applications/:id/cancelCancel (pre-effectuation)
POST/api/v1/applications/:id/terminateTerminate (post-effectuation)
GET/api/v1/applications/:id/payment_redirectGet carrier payment form data
*** #### Inline Validation Every `POST`, `PUT`, and `GET` response includes an `errors` array: ```json { "application_id": "HSA000000001", "errors": [ { "field": "applicants.primary.ssn", "code": "missing_required_field", "message": "Primary applicant SSN is required for submission" } ] } ``` When `errors` is empty, the application is ready to submit. *** #### Payment Some carriers require payment information as part of the application. The response includes `payment_instructions`:
FieldWhen true
payment_required_with_submissionInclude the payment_method object before calling submit.
payment_redirect_url_supportedGenerate a redirect URL to the carrier's payment page.
pay_by_phone_supportedCarrier accepts phone payments. payment_phone_number provided.
The `GET /applications/:id` response includes a `payment` object with carrier-reported payment data (status, paid-through date, balance due, autopay indicator) when available. If the carrier does not provide this data, the `payment` value will be `null`. {% hint style="info" %} In-flow payment support (`payment_method` in the Application request body, `PUT /payment_method` endpoint) is planned as a fast-follow addition. Sensitive payment fields will be sent through a PCI-compliant proxy URL provided by HealthSherpa, encrypted in transit and at rest. {% endhint %} *** #### Webhooks Both enrollment paths (EnrollConnect and Deeplink) generate the same webhook events. If you are already subscribed to: * [Submission Confirmation](https://docs.ichra.healthsherpa.com/api-reference/webhooks-api/submission-confirmation-api): fires when an application is submitted. * [Policy Status](https://docs.ichra.healthsherpa.com/api-reference/webhooks-api/policy-status-api): fires on status changes (effectuated, cancelled, terminated) with payment data. No additional setup is required. These webhooks work for both deeplink and EnrollConnect submissions. *** #### API Specification ## Create application > Creates a new enrollment application in draft state.\ > Payment information is managed separately via\ > \`PUT /api/v1/applications/{id}/payment\_method\`.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"schemas":{"ApplicationCreateRequest":{"type":"object","description":"Canonical application schema. This schema is shared between the EnrollConnect API\n(`POST /api/v1/applications`) and the Application Deeplink (`POST /public/ichra/off_ex`).\nBuild your payload once and send it to either endpoint.\n","required":["plan_hios_id","plan_year","applicants","residential_address"],"properties":{"external_id":{"type":"string","description":"Your unique identifier for this application."},"_agent_id":{"type":"string","nullable":true,"description":"HealthSherpa-provided agent identifier (slug). Optional for API.\nWhen provided, the application appears under this agent's book\nof business in HealthSherpa. When omitted, the agent defaults\nto the one associated with your platform account.\nRequired for deeplink.\n"},"tpa_slug":{"type":"string","description":"HealthSherpa-assigned TPA identifier (provided during onboarding)."},"plan_hios_id":{"type":"string","description":"14-character HIOS plan ID."},"plan_year":{"type":"integer"},"desired_effective_date":{"type":"string","format":"date","description":"Optional. When omitted, the carrier auto-determines the effective date based on the SEP type and event date (recommended).\nWhen provided, the date must be one of the carrier's valid effective dates for the given SEP reason and event date.\nIf the date is invalid, the API returns a 422 with either the list of valid dates to choose from, or a message\nindicating that effective date selection is not available for the given enrollment parameters (meaning the carrier\ndoes not allow date selection for this SEP type). There is no endpoint to query valid dates ahead of time.\n"},"agent_of_record":{"$ref":"#/components/schemas/AgentOfRecord"},"applicants":{"$ref":"#/components/schemas/Applicants"},"residential_address":{"$ref":"#/components/schemas/Address"},"mailing_address":{"$ref":"#/components/schemas/MailingAddress"},"hra":{"$ref":"#/components/schemas/HRA"},"special_enrollment_period":{"$ref":"#/components/schemas/SpecialEnrollmentPeriod"},"attestations":{"$ref":"#/components/schemas/Attestations"},"signatures":{"$ref":"#/components/schemas/Signatures"},"communication_preferences":{"$ref":"#/components/schemas/CommunicationPreferences"},"american_indian_or_alaskan_native_in_household":{"type":"boolean"},"analytics":{"$ref":"#/components/schemas/Analytics"}}},"AgentOfRecord":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"national_producer_number":{"type":"string","description":"1-10 digits, must not start with 0."},"carrier_producer_code":{"type":"string","description":"Carrier-specific agent identifier. For Elevance, this is the\n10-character uppercase string they generate (ends in Y or Z).\n"},"state_license_number":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"fax_number":{"type":"string"},"address":{"$ref":"#/components/schemas/SimpleAddress"},"signature":{"type":"string"}}},"SimpleAddress":{"type":"object","properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"}}},"Applicants":{"type":"object","required":["primary"],"properties":{"primary":{"$ref":"#/components/schemas/PrimaryApplicant"},"dependents":{"type":"array","items":{"$ref":"#/components/schemas/Dependent"}}}},"PrimaryApplicant":{"type":"object","required":["first_name","last_name","date_of_birth","gender"],"properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"suffix":{"type":"string","enum":["Jr.","Sr.","II","III","IV","V"]},"ssn":{"type":"string","description":"9 digits, no dashes. Encrypted at rest."},"itin":{"type":"string","description":"Individual Taxpayer Identification Number. Alternative to SSN."},"date_of_birth":{"type":"string","format":"date"},"gender":{"type":"string","enum":["male","female"],"description":"Most states accept `male`/`female`. NY also accepts `x`."},"married":{"type":"boolean"},"us_citizen":{"type":"boolean"},"resides_in_state":{"type":"boolean"},"uses_tobacco":{"type":"boolean","description":"Tobacco use in the last 6 months."},"tobacco_not_applicable":{"type":"boolean","description":"Set to `true` if tobacco question is not applicable for this applicant."},"race_ethnicity":{"type":"string","enum":["white","black_or_african_american","american_indian_or_alaskan_native","asian_indian","chinese","filipino","japanese","korean","vietnamese","native_hawaiian","guamanian_or_chamorro","samoan","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin":{"type":"string","enum":["yes","no","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin_description":{"type":"string","enum":["cuban","mexican_mexican_american_or_chicanx","puerto_rican","other_hispanic_latino_or_spanish_origin","decline_to_answer"],"description":"Required when hispanic_origin is \"yes\"."},"language_spoken":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"language_written":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"external_id":{"type":"string","description":"Your identifier for this member."},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"phone_type":{"type":"string","enum":["home","work","cell"]},"secondary_phone":{"type":"string","description":"Secondary contact phone number."},"full_time_student":{"type":"boolean"},"graduation_date":{"type":"string","format":"date","description":"Required if `full_time_student` is `true`."},"has_disability":{"type":"boolean","description":"Affects dependent age eligibility limits."},"medicare_eligible":{"type":"boolean","description":"Whether the applicant is eligible for Medicare."},"enrolled_in_medicare":{"type":"boolean"},"enrolled_in_medicare_parts_a_or_b":{"type":"boolean"},"enrolled_in_medicaid_chip_or_other_gov_program":{"type":"boolean"},"veteran_or_active_duty_military":{"type":"boolean"},"currently_incarcerated":{"type":"boolean"},"has_eligible_immigration_status":{"type":"boolean"},"existing_coverage":{"$ref":"#/components/schemas/ExistingCoverage"},"guardian":{"$ref":"#/components/schemas/Guardian"},"responsible_party":{"$ref":"#/components/schemas/ResponsibleParty"},"translator":{"$ref":"#/components/schemas/Translator"},"signature":{"type":"string","description":"Primary applicant's typed full legal name. Required for submission. This field is on the applicant object, NOT under the top-level signatures object."},"children_live_with_primary":{"type":"boolean"},"has_pediatric_dental_coverage":{"type":"boolean"},"previously_applied":{"type":"boolean"},"previously_applied_member_id":{"type":"string"},"primary_requesting_coverage":{"type":"boolean","description":"Whether the primary applicant is requesting coverage for themselves."}}},"ExistingCoverage":{"type":"object","properties":{"has_existing_coverage":{"type":"boolean"},"plan_replaces_existing_coverage":{"type":"boolean"},"type":{"type":"string","enum":["issuer","government"],"description":"`issuer`: coverage with another issuer.\n`government`: government program (Medicare, Medicaid, etc.).\n"},"insurer":{"type":"string"},"policy_id":{"type":"string"},"policyholder_name":{"type":"string"},"start_date":{"type":"string","format":"date"},"term_date":{"type":"string","format":"date"},"will_continue":{"type":"boolean","description":"Whether the existing coverage will continue alongside the new plan."}}},"Guardian":{"type":"object","description":"Required for primary applicants under 18.","properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"suffix":{"type":"string","enum":["Jr.","Sr.","II","III","IV","V"]},"gender":{"type":"string","enum":["male","female"]},"relationship":{"type":"string","enum":["parent","legal_guardian","grandparent","other"]},"date_of_birth":{"type":"string","format":"date"},"relationship_other":{"type":"string","description":"Required if `relationship` is `other`."},"email":{"type":"string","format":"email"},"home_phone":{"type":"string"},"alternate_phone":{"type":"string"},"mailing_address":{"type":"object","description":"Guardian's mailing address, if different from the applicant's residential address.","properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"},"fips_code":{"type":"string"}}}}},"ResponsibleParty":{"type":"object","description":"Responsible party for a minor applicant, when someone other than the guardian is financially responsible. Required by Security Health, Sanford, Oscar, and UHC.\n","properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"date_of_birth":{"type":"string","format":"date"},"sex":{"type":"string","enum":["male","female"]},"relationship":{"type":"string","enum":["parent_guardian","sibling"]},"phone":{"type":"string"},"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"}}},"Translator":{"type":"object","description":"Translator assisting the applicant. Required by some carriers when the applicant requires language assistance.\n","properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"reason":{"type":"string","description":"Why a translator is needed."}}},"Dependent":{"type":"object","required":["first_name","last_name","date_of_birth","gender","relationship"],"properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"suffix":{"type":"string","enum":["Jr.","Sr.","II","III","IV","V"]},"ssn":{"type":"string"},"itin":{"type":"string","description":"Individual Taxpayer Identification Number. Alternative to SSN."},"date_of_birth":{"type":"string","format":"date"},"gender":{"type":"string","enum":["male","female"]},"relationship":{"type":"string","enum":["spouse","domestic_partner","child","parent","stepparent","parent_in_law","sibling","other"],"description":"`spouse`, `domestic_partner`, `child` are supported by all carriers.\n`parent`, `stepparent`, `parent_in_law`, `sibling`, `other` are accepted\nby select carriers and states. Check carrier configuration for availability.\n"},"married":{"type":"boolean"},"us_citizen":{"type":"boolean"},"resides_in_state":{"type":"boolean"},"uses_tobacco":{"type":"boolean"},"tobacco_not_applicable":{"type":"boolean","description":"Set to `true` if tobacco question is not applicable for this applicant."},"race_ethnicity":{"type":"string","enum":["white","black_or_african_american","american_indian_or_alaskan_native","asian_indian","chinese","filipino","japanese","korean","vietnamese","native_hawaiian","guamanian_or_chamorro","samoan","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin":{"type":"string","enum":["yes","no","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin_description":{"type":"string","enum":["cuban","mexican_mexican_american_or_chicanx","puerto_rican","other_hispanic_latino_or_spanish_origin","decline_to_answer"],"description":"Required when hispanic_origin is \"yes\"."},"language_spoken":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"language_written":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"external_id":{"type":"string","description":"Your identifier for this member."},"full_time_student":{"type":"boolean"},"graduation_date":{"type":"string","format":"date","description":"Required if `full_time_student` is `true`."},"has_disability":{"type":"boolean","description":"Affects dependent age eligibility limits."},"medicare_eligible":{"type":"boolean"},"enrolled_in_medicare":{"type":"boolean"},"enrolled_in_medicare_parts_a_or_b":{"type":"boolean"},"enrolled_in_medicaid_chip_or_other_gov_program":{"type":"boolean"},"veteran_or_active_duty_military":{"type":"boolean"},"currently_incarcerated":{"type":"boolean"},"has_eligible_immigration_status":{"type":"boolean"},"existing_coverage":{"$ref":"#/components/schemas/ExistingCoverage"},"alternate_address":{"$ref":"#/components/schemas/AlternateAddress"},"guardian":{"$ref":"#/components/schemas/Guardian"}}},"AlternateAddress":{"type":"object","description":"Address for a dependent living at a different address than the primary applicant.","properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"},"fips_code":{"type":"string"},"reason":{"type":"string","description":"Reason the dependent has a different address."}}},"Address":{"type":"object","required":["street_address_1","city","state","zip_code"],"properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"Two-letter state code."},"zip_code":{"type":"string","pattern":"^\\d{5}$"},"fips_code":{"type":"string","description":"5-digit FIPS county code. See [FIPS County Codes](https://docs.ichra.healthsherpa.com/api-reference/supporting-material/fips-county-codes)."}}},"MailingAddress":{"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"different_from_home_address":{"type":"boolean","default":false},"billing_use_only":{"type":"boolean","default":false}}}]},"HRA":{"type":"object","description":"Health Reimbursement Arrangement details. Applies to the primary applicant\n(the employee receiving the HRA offer). If the ICHRA is affordable, all\nhousehold members are ineligible for premium tax credits.\n","properties":{"offered_hra":{"type":"boolean","nullable":true,"description":"`true`: applicant is offered an HRA.\n`false`: applicant is not offered an HRA.\n`null`: unknown.\n"},"type":{"type":"string","enum":["ichra","qsehra"]},"amount":{"type":"number","format":"float","description":"Monthly contribution in USD."},"contribution_covers":{"type":"string","enum":["premium","premium_oop"],"description":"`premium`: premiums only.\n`premium_oop`: premiums and out-of-pocket costs.\n"},"used_for_spousal_or_family_premiums":{"type":"string","enum":["true","false","unknown"],"description":"Whether the HRA is used for spousal or family premiums. Relevant for QSEHRA 834 indicators."},"start":{"type":"string","format":"date"},"employer":{"$ref":"#/components/schemas/Employer"},"premium_payer":{"type":"string"},"household_size":{"type":"integer"},"annual_household_income":{"type":"number","format":"float"},"annual_household_income_determination":{"type":"string"}}},"Employer":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","description":"Your identifier for this employer group."},"phone":{"type":"string"},"fein":{"type":"string","description":"9-digit Federal Employer Identification Number."},"address":{"$ref":"#/components/schemas/Address"}}},"SpecialEnrollmentPeriod":{"type":"object","properties":{"event_type":{"type":"string","enum":["birth","adoption","death","divorce","marriage","domestic_partnership","child_support","loss_of_mec","loss_of_dependent","dependent_lost_coverage","loss_of_pregnancy_coverage","end_of_non_calendar_year_policy","change_in_household_status","lost_aptc","relocation","nj_county_change","offered_ichra","offered_qsehra","mandated_covered_dependent","released_from_incarceration","returning_active_duty","provider_not_participating_in_prior_plan","issuer_violated_contract","misinformed","domestic_abuse","family_care_app_ineligible","pregnancy","other"],"description":"Standardized qualifying event type. HealthSherpa maps these to\ncarrier-specific values automatically. Send the canonical value\nregardless of carrier.\n\n`pregnancy` is accepted in CO, VA, NJ, MD.\nFor ICHRA enrollments, `offered_ichra` is the most common reason.\nSee [Carrier-Specific SEP Info](https://docs.ichra.healthsherpa.com/api-reference/supporting-material/carrier-specific-deeplink-info) for per-carrier availability.\n"},"event_date":{"type":"string","format":"date"}}},"Attestations":{"type":"object","properties":{"agrees_issuer_attestations":{"type":"boolean"},"broker_signature_attestation":{"type":"boolean"},"electronic_signature_consent":{"type":"boolean"},"disclosure_statement_accepted":{"type":"boolean"},"coverage_replacement_attestation_accepted":{"type":"boolean"},"pediatric_dental":{"type":"string","enum":["purchased_separately","not_applicable"],"description":"Pediatric dental attestation. `purchased_separately`: pediatric dental purchased via stand-alone dental plan. `not_applicable`: no children under 19 on the application.\n"},"agent_submitted_application":{"type":"boolean"},"agent_provided_consumer_marketing_materials":{"type":"boolean"},"agent_advised_consumer_of_product_features":{"type":"boolean"},"agent_retained_signed_application_copy":{"type":"boolean"},"consumer_working_with_agent":{"type":"boolean"},"spouse_or_dependent_authorization":{"type":"boolean","description":"Authorization for dependents/spouse to be included on the application."}}},"Signatures":{"type":"object","properties":{"signature_date":{"type":"string","format":"date","description":"Date the application was signed. Required for submission. This is separate from applicants.primary.signature (the typed name)."},"pediatric_dental_signature":{"type":"string"},"pediatric_dental_signature_date":{"type":"string","format":"date","nullable":true},"translator_signature_date":{"type":"string","format":"date","nullable":true},"state_supplement_primary_signature":{"type":"string","description":"State-required supplemental form signature (primary applicant). Required for CO, UT, NJ."},"state_supplement_spouse_signature":{"type":"string","description":"State-required supplemental form signature (spouse). Required for UT."},"state_supplement_disclosures_signature":{"type":"string","description":"State-required supplemental form disclosures signature (primary applicant). Required for CO."}}},"CommunicationPreferences":{"type":"object","properties":{"application_notification_email":{"type":"boolean"},"application_notification_call":{"type":"boolean"},"application_notification_text":{"type":"boolean"},"email_contact_consent":{"type":"boolean"},"marketing_contact_consent":{"type":"boolean"},"decline_marketing_contact":{"type":"boolean"},"preferred_communication_method":{"type":"string","enum":["email","phone","mail"]},"agrees_hsa_contact_opt_in":{"type":"boolean"},"communication_preference_affirmed":{"type":"boolean","description":"Whether the applicant has affirmed their communication preferences."}}},"Analytics":{"type":"object","description":"Optional tracking and attribution parameters.","properties":{"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"}}},"ApplicationResponse":{"type":"object","properties":{"application_id":{"type":"string"},"external_id":{"type":"string"},"tpa_slug":{"type":"string"},"policy_status":{"type":"string","enum":["draft","pending_effectuation","effectuated","submission_failed","cancelled","terminated"],"description":"`draft` when the application has not yet been submitted.\nTransitions to `pending_effectuation` on successful submission.\n`submission_failed` when the asynchronous carrier submission\nfailed after the submit endpoint returned 202. Poll the\napplication to detect this state and check `errors` for details.\n"},"document_status":{"type":"string","enum":["none_needed","required","uploaded","verified","denied"],"description":"SEP document verification status.\n`none_needed`: no documentation required.\n`required`: documentation required but not yet uploaded.\n`uploaded`: documentation uploaded, pending verification.\n`verified`: documentation verified.\n`denied`: documentation denied.\n","nullable":true},"sep_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submitted_at":{"type":"string","format":"date-time","nullable":true},"desired_effective_date":{"type":"string","format":"date"},"plan_hios_id":{"type":"string"},"plan_year":{"type":"integer"},"issuer_hios_id":{"type":"string"},"payment_instructions":{"$ref":"#/components/schemas/PaymentInstructions"},"payment":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/PolicyPaymentStatus"}],"description":"Carrier-reported payment status. Only present after\nsubmission. For carriers that use payment redirect, this\ndata depends on the carrier reporting it back and may not\nbe immediately available.\n"},"policies":{"type":"array","items":{"$ref":"#/components/schemas/PolicyDetail"}},"application":{"type":"object","description":"Echo of the application data as stored."},"errors":{"type":"array","description":"Submission-readiness errors. Present on every POST, PUT, and GET\nresponse. An empty array means the application is ready to submit.\nEach entry uses the same `ErrorDetail` structure as top-level API\nerrors, with `code`, `message`, and optional `field`.\nCarrier-specific required fields (e.g., SSN for most carriers,\nguardian for minor applicants) are enforced dynamically based\non the selected plan's carrier.\n","items":{"$ref":"#/components/schemas/ValidationDetail"}},"next_actions":{"type":"array","description":"State-aware list of actions the partner can take on this\napplication. Changes based on `policy_status`, validation\nstate, and carrier capabilities. Use `rel` to identify\nthe action, `href` for the URL, and `method` for the\nHTTP verb.\n","items":{"$ref":"#/components/schemas/NextAction"}}}},"PaymentInstructions":{"type":"object","description":"Carrier-specific payment guidance.","properties":{"payment_required_with_submission":{"type":"boolean","description":"`true` when payment must be set via\n`PUT /applications/:id/payment_method` before submission.\nCurrently applies to Cigna and Elevance (in-flow).\n"},"payment_redirect_supported":{"type":"boolean","description":"`true` when the carrier supports browser-based payment\nredirect. Use `GET /applications/:id/payment_redirect` to\nretrieve the endpoint URL and form fields.\n"},"pay_by_phone_supported":{"type":"boolean"},"payment_phone_number":{"type":"string","nullable":true}}},"PolicyPaymentStatus":{"type":"object","description":"Carrier-reported payment information. All fields are nullable\nbecause data availability depends on whether the carrier has\nreported payment status. For carriers using payment redirect,\nthis information may not be available until the carrier sends\nan update.\n","properties":{"payment_status":{"type":"string","nullable":true,"description":"Carrier-reported payment state."},"payment_status_updated_date":{"type":"string","format":"date","nullable":true},"grace_period_start_date":{"type":"string","format":"date","nullable":true},"paid_through_date":{"type":"string","format":"date","nullable":true},"past_due_member_responsibility_balance_due":{"type":"string","nullable":true},"current_member_responsibility_balance_due":{"type":"string","nullable":true},"autopay_indicator":{"type":"boolean","nullable":true}}},"PolicyDetail":{"type":"object","properties":{"policy_id":{"type":"string"},"effective_date":{"type":"string","format":"date"},"expiration_date":{"type":"string","format":"date"},"status":{"type":"string","enum":["pending_effectuation","effectuated","cancelled","terminated"]},"plan_hios_id":{"type":"string"},"gross_premium":{"type":"number","format":"float"},"members":{"type":"array","items":{"type":"object","properties":{"member_id":{"type":"string"},"effective_date":{"type":"string","format":"date"},"removed_date":{"type":"string","format":"date","nullable":true}}}},"agent_of_record":{"type":"object","properties":{"npn":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"state_license_number":{"type":"string"},"email":{"type":"string"}}},"payment":{"$ref":"#/components/schemas/PolicyPaymentStatus"}}},"ValidationDetail":{"description":"Alias for ErrorDetail. Validation errors in `errors`\nuse the same structure as top-level API errors.\n","allOf":[{"$ref":"#/components/schemas/ErrorDetail"}]},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}},"NextAction":{"type":"object","description":"A hypermedia action link describing an available operation on the application.","required":["rel","href","method"],"properties":{"rel":{"type":"string","description":"Relation type identifying the action. Possible values:\n`self`, `update`, `validate`, `submit`, `cancel`,\n`terminate`, `payment_redirect`,\n`upload_supporting_documentation`.\n"},"href":{"type":"string","description":"Relative URL for the action."},"method":{"type":"string","enum":["GET","PUT","POST"],"description":"HTTP method to use."},"required":{"type":"boolean","description":"When `true`, this action must be completed before the\napplication can be submitted. Used for submission\nprerequisites like uploading supporting documentation\nor completing payment. Not present on most actions.\n"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"responses":{"BadRequest":{"description":"Malformed or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"Syntactically valid but semantically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications":{"post":{"summary":"Create application","description":"Creates a new enrollment application in draft state.\nPayment information is managed separately via\n`PUT /api/v1/applications/{id}/payment_method`.\n","operationId":"createApplication","tags":["Applications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationCreateRequest"}}}},"responses":{"201":{"description":"Application created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}} ``` ## Update application > Full replacement of application state. Partial updates are not supported.\ > Applications can only be updated before submission.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"parameters":{"ApplicationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"HealthSherpa application ID."}},"schemas":{"ApplicationCreateRequest":{"type":"object","description":"Canonical application schema. This schema is shared between the EnrollConnect API\n(`POST /api/v1/applications`) and the Application Deeplink (`POST /public/ichra/off_ex`).\nBuild your payload once and send it to either endpoint.\n","required":["plan_hios_id","plan_year","applicants","residential_address"],"properties":{"external_id":{"type":"string","description":"Your unique identifier for this application."},"_agent_id":{"type":"string","nullable":true,"description":"HealthSherpa-provided agent identifier (slug). Optional for API.\nWhen provided, the application appears under this agent's book\nof business in HealthSherpa. When omitted, the agent defaults\nto the one associated with your platform account.\nRequired for deeplink.\n"},"tpa_slug":{"type":"string","description":"HealthSherpa-assigned TPA identifier (provided during onboarding)."},"plan_hios_id":{"type":"string","description":"14-character HIOS plan ID."},"plan_year":{"type":"integer"},"desired_effective_date":{"type":"string","format":"date","description":"Optional. When omitted, the carrier auto-determines the effective date based on the SEP type and event date (recommended).\nWhen provided, the date must be one of the carrier's valid effective dates for the given SEP reason and event date.\nIf the date is invalid, the API returns a 422 with either the list of valid dates to choose from, or a message\nindicating that effective date selection is not available for the given enrollment parameters (meaning the carrier\ndoes not allow date selection for this SEP type). There is no endpoint to query valid dates ahead of time.\n"},"agent_of_record":{"$ref":"#/components/schemas/AgentOfRecord"},"applicants":{"$ref":"#/components/schemas/Applicants"},"residential_address":{"$ref":"#/components/schemas/Address"},"mailing_address":{"$ref":"#/components/schemas/MailingAddress"},"hra":{"$ref":"#/components/schemas/HRA"},"special_enrollment_period":{"$ref":"#/components/schemas/SpecialEnrollmentPeriod"},"attestations":{"$ref":"#/components/schemas/Attestations"},"signatures":{"$ref":"#/components/schemas/Signatures"},"communication_preferences":{"$ref":"#/components/schemas/CommunicationPreferences"},"american_indian_or_alaskan_native_in_household":{"type":"boolean"},"analytics":{"$ref":"#/components/schemas/Analytics"}}},"AgentOfRecord":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"national_producer_number":{"type":"string","description":"1-10 digits, must not start with 0."},"carrier_producer_code":{"type":"string","description":"Carrier-specific agent identifier. For Elevance, this is the\n10-character uppercase string they generate (ends in Y or Z).\n"},"state_license_number":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"fax_number":{"type":"string"},"address":{"$ref":"#/components/schemas/SimpleAddress"},"signature":{"type":"string"}}},"SimpleAddress":{"type":"object","properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"}}},"Applicants":{"type":"object","required":["primary"],"properties":{"primary":{"$ref":"#/components/schemas/PrimaryApplicant"},"dependents":{"type":"array","items":{"$ref":"#/components/schemas/Dependent"}}}},"PrimaryApplicant":{"type":"object","required":["first_name","last_name","date_of_birth","gender"],"properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"suffix":{"type":"string","enum":["Jr.","Sr.","II","III","IV","V"]},"ssn":{"type":"string","description":"9 digits, no dashes. Encrypted at rest."},"itin":{"type":"string","description":"Individual Taxpayer Identification Number. Alternative to SSN."},"date_of_birth":{"type":"string","format":"date"},"gender":{"type":"string","enum":["male","female"],"description":"Most states accept `male`/`female`. NY also accepts `x`."},"married":{"type":"boolean"},"us_citizen":{"type":"boolean"},"resides_in_state":{"type":"boolean"},"uses_tobacco":{"type":"boolean","description":"Tobacco use in the last 6 months."},"tobacco_not_applicable":{"type":"boolean","description":"Set to `true` if tobacco question is not applicable for this applicant."},"race_ethnicity":{"type":"string","enum":["white","black_or_african_american","american_indian_or_alaskan_native","asian_indian","chinese","filipino","japanese","korean","vietnamese","native_hawaiian","guamanian_or_chamorro","samoan","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin":{"type":"string","enum":["yes","no","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin_description":{"type":"string","enum":["cuban","mexican_mexican_american_or_chicanx","puerto_rican","other_hispanic_latino_or_spanish_origin","decline_to_answer"],"description":"Required when hispanic_origin is \"yes\"."},"language_spoken":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"language_written":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"external_id":{"type":"string","description":"Your identifier for this member."},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"phone_type":{"type":"string","enum":["home","work","cell"]},"secondary_phone":{"type":"string","description":"Secondary contact phone number."},"full_time_student":{"type":"boolean"},"graduation_date":{"type":"string","format":"date","description":"Required if `full_time_student` is `true`."},"has_disability":{"type":"boolean","description":"Affects dependent age eligibility limits."},"medicare_eligible":{"type":"boolean","description":"Whether the applicant is eligible for Medicare."},"enrolled_in_medicare":{"type":"boolean"},"enrolled_in_medicare_parts_a_or_b":{"type":"boolean"},"enrolled_in_medicaid_chip_or_other_gov_program":{"type":"boolean"},"veteran_or_active_duty_military":{"type":"boolean"},"currently_incarcerated":{"type":"boolean"},"has_eligible_immigration_status":{"type":"boolean"},"existing_coverage":{"$ref":"#/components/schemas/ExistingCoverage"},"guardian":{"$ref":"#/components/schemas/Guardian"},"responsible_party":{"$ref":"#/components/schemas/ResponsibleParty"},"translator":{"$ref":"#/components/schemas/Translator"},"signature":{"type":"string","description":"Primary applicant's typed full legal name. Required for submission. This field is on the applicant object, NOT under the top-level signatures object."},"children_live_with_primary":{"type":"boolean"},"has_pediatric_dental_coverage":{"type":"boolean"},"previously_applied":{"type":"boolean"},"previously_applied_member_id":{"type":"string"},"primary_requesting_coverage":{"type":"boolean","description":"Whether the primary applicant is requesting coverage for themselves."}}},"ExistingCoverage":{"type":"object","properties":{"has_existing_coverage":{"type":"boolean"},"plan_replaces_existing_coverage":{"type":"boolean"},"type":{"type":"string","enum":["issuer","government"],"description":"`issuer`: coverage with another issuer.\n`government`: government program (Medicare, Medicaid, etc.).\n"},"insurer":{"type":"string"},"policy_id":{"type":"string"},"policyholder_name":{"type":"string"},"start_date":{"type":"string","format":"date"},"term_date":{"type":"string","format":"date"},"will_continue":{"type":"boolean","description":"Whether the existing coverage will continue alongside the new plan."}}},"Guardian":{"type":"object","description":"Required for primary applicants under 18.","properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"suffix":{"type":"string","enum":["Jr.","Sr.","II","III","IV","V"]},"gender":{"type":"string","enum":["male","female"]},"relationship":{"type":"string","enum":["parent","legal_guardian","grandparent","other"]},"date_of_birth":{"type":"string","format":"date"},"relationship_other":{"type":"string","description":"Required if `relationship` is `other`."},"email":{"type":"string","format":"email"},"home_phone":{"type":"string"},"alternate_phone":{"type":"string"},"mailing_address":{"type":"object","description":"Guardian's mailing address, if different from the applicant's residential address.","properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"},"fips_code":{"type":"string"}}}}},"ResponsibleParty":{"type":"object","description":"Responsible party for a minor applicant, when someone other than the guardian is financially responsible. Required by Security Health, Sanford, Oscar, and UHC.\n","properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"date_of_birth":{"type":"string","format":"date"},"sex":{"type":"string","enum":["male","female"]},"relationship":{"type":"string","enum":["parent_guardian","sibling"]},"phone":{"type":"string"},"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"}}},"Translator":{"type":"object","description":"Translator assisting the applicant. Required by some carriers when the applicant requires language assistance.\n","properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"reason":{"type":"string","description":"Why a translator is needed."}}},"Dependent":{"type":"object","required":["first_name","last_name","date_of_birth","gender","relationship"],"properties":{"first_name":{"type":"string"},"middle_name":{"type":"string"},"last_name":{"type":"string"},"suffix":{"type":"string","enum":["Jr.","Sr.","II","III","IV","V"]},"ssn":{"type":"string"},"itin":{"type":"string","description":"Individual Taxpayer Identification Number. Alternative to SSN."},"date_of_birth":{"type":"string","format":"date"},"gender":{"type":"string","enum":["male","female"]},"relationship":{"type":"string","enum":["spouse","domestic_partner","child","parent","stepparent","parent_in_law","sibling","other"],"description":"`spouse`, `domestic_partner`, `child` are supported by all carriers.\n`parent`, `stepparent`, `parent_in_law`, `sibling`, `other` are accepted\nby select carriers and states. Check carrier configuration for availability.\n"},"married":{"type":"boolean"},"us_citizen":{"type":"boolean"},"resides_in_state":{"type":"boolean"},"uses_tobacco":{"type":"boolean"},"tobacco_not_applicable":{"type":"boolean","description":"Set to `true` if tobacco question is not applicable for this applicant."},"race_ethnicity":{"type":"string","enum":["white","black_or_african_american","american_indian_or_alaskan_native","asian_indian","chinese","filipino","japanese","korean","vietnamese","native_hawaiian","guamanian_or_chamorro","samoan","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin":{"type":"string","enum":["yes","no","decline_to_answer"],"description":"Required by some carriers. Use \"decline_to_answer\" if not collected."},"hispanic_origin_description":{"type":"string","enum":["cuban","mexican_mexican_american_or_chicanx","puerto_rican","other_hispanic_latino_or_spanish_origin","decline_to_answer"],"description":"Required when hispanic_origin is \"yes\"."},"language_spoken":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"language_written":{"type":"string","enum":["english","spanish","arabic","chinese","french_creole","french","german","gujarati","hindi","korean","polish","portuguese","russian","tagalog","urdu","vietnamese","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"external_id":{"type":"string","description":"Your identifier for this member."},"full_time_student":{"type":"boolean"},"graduation_date":{"type":"string","format":"date","description":"Required if `full_time_student` is `true`."},"has_disability":{"type":"boolean","description":"Affects dependent age eligibility limits."},"medicare_eligible":{"type":"boolean"},"enrolled_in_medicare":{"type":"boolean"},"enrolled_in_medicare_parts_a_or_b":{"type":"boolean"},"enrolled_in_medicaid_chip_or_other_gov_program":{"type":"boolean"},"veteran_or_active_duty_military":{"type":"boolean"},"currently_incarcerated":{"type":"boolean"},"has_eligible_immigration_status":{"type":"boolean"},"existing_coverage":{"$ref":"#/components/schemas/ExistingCoverage"},"alternate_address":{"$ref":"#/components/schemas/AlternateAddress"},"guardian":{"$ref":"#/components/schemas/Guardian"}}},"AlternateAddress":{"type":"object","description":"Address for a dependent living at a different address than the primary applicant.","properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip_code":{"type":"string"},"fips_code":{"type":"string"},"reason":{"type":"string","description":"Reason the dependent has a different address."}}},"Address":{"type":"object","required":["street_address_1","city","state","zip_code"],"properties":{"street_address_1":{"type":"string"},"street_address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"Two-letter state code."},"zip_code":{"type":"string","pattern":"^\\d{5}$"},"fips_code":{"type":"string","description":"5-digit FIPS county code. See [FIPS County Codes](https://docs.ichra.healthsherpa.com/api-reference/supporting-material/fips-county-codes)."}}},"MailingAddress":{"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"different_from_home_address":{"type":"boolean","default":false},"billing_use_only":{"type":"boolean","default":false}}}]},"HRA":{"type":"object","description":"Health Reimbursement Arrangement details. Applies to the primary applicant\n(the employee receiving the HRA offer). If the ICHRA is affordable, all\nhousehold members are ineligible for premium tax credits.\n","properties":{"offered_hra":{"type":"boolean","nullable":true,"description":"`true`: applicant is offered an HRA.\n`false`: applicant is not offered an HRA.\n`null`: unknown.\n"},"type":{"type":"string","enum":["ichra","qsehra"]},"amount":{"type":"number","format":"float","description":"Monthly contribution in USD."},"contribution_covers":{"type":"string","enum":["premium","premium_oop"],"description":"`premium`: premiums only.\n`premium_oop`: premiums and out-of-pocket costs.\n"},"used_for_spousal_or_family_premiums":{"type":"string","enum":["true","false","unknown"],"description":"Whether the HRA is used for spousal or family premiums. Relevant for QSEHRA 834 indicators."},"start":{"type":"string","format":"date"},"employer":{"$ref":"#/components/schemas/Employer"},"premium_payer":{"type":"string"},"household_size":{"type":"integer"},"annual_household_income":{"type":"number","format":"float"},"annual_household_income_determination":{"type":"string"}}},"Employer":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","description":"Your identifier for this employer group."},"phone":{"type":"string"},"fein":{"type":"string","description":"9-digit Federal Employer Identification Number."},"address":{"$ref":"#/components/schemas/Address"}}},"SpecialEnrollmentPeriod":{"type":"object","properties":{"event_type":{"type":"string","enum":["birth","adoption","death","divorce","marriage","domestic_partnership","child_support","loss_of_mec","loss_of_dependent","dependent_lost_coverage","loss_of_pregnancy_coverage","end_of_non_calendar_year_policy","change_in_household_status","lost_aptc","relocation","nj_county_change","offered_ichra","offered_qsehra","mandated_covered_dependent","released_from_incarceration","returning_active_duty","provider_not_participating_in_prior_plan","issuer_violated_contract","misinformed","domestic_abuse","family_care_app_ineligible","pregnancy","other"],"description":"Standardized qualifying event type. HealthSherpa maps these to\ncarrier-specific values automatically. Send the canonical value\nregardless of carrier.\n\n`pregnancy` is accepted in CO, VA, NJ, MD.\nFor ICHRA enrollments, `offered_ichra` is the most common reason.\nSee [Carrier-Specific SEP Info](https://docs.ichra.healthsherpa.com/api-reference/supporting-material/carrier-specific-deeplink-info) for per-carrier availability.\n"},"event_date":{"type":"string","format":"date"}}},"Attestations":{"type":"object","properties":{"agrees_issuer_attestations":{"type":"boolean"},"broker_signature_attestation":{"type":"boolean"},"electronic_signature_consent":{"type":"boolean"},"disclosure_statement_accepted":{"type":"boolean"},"coverage_replacement_attestation_accepted":{"type":"boolean"},"pediatric_dental":{"type":"string","enum":["purchased_separately","not_applicable"],"description":"Pediatric dental attestation. `purchased_separately`: pediatric dental purchased via stand-alone dental plan. `not_applicable`: no children under 19 on the application.\n"},"agent_submitted_application":{"type":"boolean"},"agent_provided_consumer_marketing_materials":{"type":"boolean"},"agent_advised_consumer_of_product_features":{"type":"boolean"},"agent_retained_signed_application_copy":{"type":"boolean"},"consumer_working_with_agent":{"type":"boolean"},"spouse_or_dependent_authorization":{"type":"boolean","description":"Authorization for dependents/spouse to be included on the application."}}},"Signatures":{"type":"object","properties":{"signature_date":{"type":"string","format":"date","description":"Date the application was signed. Required for submission. This is separate from applicants.primary.signature (the typed name)."},"pediatric_dental_signature":{"type":"string"},"pediatric_dental_signature_date":{"type":"string","format":"date","nullable":true},"translator_signature_date":{"type":"string","format":"date","nullable":true},"state_supplement_primary_signature":{"type":"string","description":"State-required supplemental form signature (primary applicant). Required for CO, UT, NJ."},"state_supplement_spouse_signature":{"type":"string","description":"State-required supplemental form signature (spouse). Required for UT."},"state_supplement_disclosures_signature":{"type":"string","description":"State-required supplemental form disclosures signature (primary applicant). Required for CO."}}},"CommunicationPreferences":{"type":"object","properties":{"application_notification_email":{"type":"boolean"},"application_notification_call":{"type":"boolean"},"application_notification_text":{"type":"boolean"},"email_contact_consent":{"type":"boolean"},"marketing_contact_consent":{"type":"boolean"},"decline_marketing_contact":{"type":"boolean"},"preferred_communication_method":{"type":"string","enum":["email","phone","mail"]},"agrees_hsa_contact_opt_in":{"type":"boolean"},"communication_preference_affirmed":{"type":"boolean","description":"Whether the applicant has affirmed their communication preferences."}}},"Analytics":{"type":"object","description":"Optional tracking and attribution parameters.","properties":{"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"}}},"ApplicationResponse":{"type":"object","properties":{"application_id":{"type":"string"},"external_id":{"type":"string"},"tpa_slug":{"type":"string"},"policy_status":{"type":"string","enum":["draft","pending_effectuation","effectuated","submission_failed","cancelled","terminated"],"description":"`draft` when the application has not yet been submitted.\nTransitions to `pending_effectuation` on successful submission.\n`submission_failed` when the asynchronous carrier submission\nfailed after the submit endpoint returned 202. Poll the\napplication to detect this state and check `errors` for details.\n"},"document_status":{"type":"string","enum":["none_needed","required","uploaded","verified","denied"],"description":"SEP document verification status.\n`none_needed`: no documentation required.\n`required`: documentation required but not yet uploaded.\n`uploaded`: documentation uploaded, pending verification.\n`verified`: documentation verified.\n`denied`: documentation denied.\n","nullable":true},"sep_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submitted_at":{"type":"string","format":"date-time","nullable":true},"desired_effective_date":{"type":"string","format":"date"},"plan_hios_id":{"type":"string"},"plan_year":{"type":"integer"},"issuer_hios_id":{"type":"string"},"payment_instructions":{"$ref":"#/components/schemas/PaymentInstructions"},"payment":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/PolicyPaymentStatus"}],"description":"Carrier-reported payment status. Only present after\nsubmission. For carriers that use payment redirect, this\ndata depends on the carrier reporting it back and may not\nbe immediately available.\n"},"policies":{"type":"array","items":{"$ref":"#/components/schemas/PolicyDetail"}},"application":{"type":"object","description":"Echo of the application data as stored."},"errors":{"type":"array","description":"Submission-readiness errors. Present on every POST, PUT, and GET\nresponse. An empty array means the application is ready to submit.\nEach entry uses the same `ErrorDetail` structure as top-level API\nerrors, with `code`, `message`, and optional `field`.\nCarrier-specific required fields (e.g., SSN for most carriers,\nguardian for minor applicants) are enforced dynamically based\non the selected plan's carrier.\n","items":{"$ref":"#/components/schemas/ValidationDetail"}},"next_actions":{"type":"array","description":"State-aware list of actions the partner can take on this\napplication. Changes based on `policy_status`, validation\nstate, and carrier capabilities. Use `rel` to identify\nthe action, `href` for the URL, and `method` for the\nHTTP verb.\n","items":{"$ref":"#/components/schemas/NextAction"}}}},"PaymentInstructions":{"type":"object","description":"Carrier-specific payment guidance.","properties":{"payment_required_with_submission":{"type":"boolean","description":"`true` when payment must be set via\n`PUT /applications/:id/payment_method` before submission.\nCurrently applies to Cigna and Elevance (in-flow).\n"},"payment_redirect_supported":{"type":"boolean","description":"`true` when the carrier supports browser-based payment\nredirect. Use `GET /applications/:id/payment_redirect` to\nretrieve the endpoint URL and form fields.\n"},"pay_by_phone_supported":{"type":"boolean"},"payment_phone_number":{"type":"string","nullable":true}}},"PolicyPaymentStatus":{"type":"object","description":"Carrier-reported payment information. All fields are nullable\nbecause data availability depends on whether the carrier has\nreported payment status. For carriers using payment redirect,\nthis information may not be available until the carrier sends\nan update.\n","properties":{"payment_status":{"type":"string","nullable":true,"description":"Carrier-reported payment state."},"payment_status_updated_date":{"type":"string","format":"date","nullable":true},"grace_period_start_date":{"type":"string","format":"date","nullable":true},"paid_through_date":{"type":"string","format":"date","nullable":true},"past_due_member_responsibility_balance_due":{"type":"string","nullable":true},"current_member_responsibility_balance_due":{"type":"string","nullable":true},"autopay_indicator":{"type":"boolean","nullable":true}}},"PolicyDetail":{"type":"object","properties":{"policy_id":{"type":"string"},"effective_date":{"type":"string","format":"date"},"expiration_date":{"type":"string","format":"date"},"status":{"type":"string","enum":["pending_effectuation","effectuated","cancelled","terminated"]},"plan_hios_id":{"type":"string"},"gross_premium":{"type":"number","format":"float"},"members":{"type":"array","items":{"type":"object","properties":{"member_id":{"type":"string"},"effective_date":{"type":"string","format":"date"},"removed_date":{"type":"string","format":"date","nullable":true}}}},"agent_of_record":{"type":"object","properties":{"npn":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"state_license_number":{"type":"string"},"email":{"type":"string"}}},"payment":{"$ref":"#/components/schemas/PolicyPaymentStatus"}}},"ValidationDetail":{"description":"Alias for ErrorDetail. Validation errors in `errors`\nuse the same structure as top-level API errors.\n","allOf":[{"$ref":"#/components/schemas/ErrorDetail"}]},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}},"NextAction":{"type":"object","description":"A hypermedia action link describing an available operation on the application.","required":["rel","href","method"],"properties":{"rel":{"type":"string","description":"Relation type identifying the action. Possible values:\n`self`, `update`, `validate`, `submit`, `cancel`,\n`terminate`, `payment_redirect`,\n`upload_supporting_documentation`.\n"},"href":{"type":"string","description":"Relative URL for the action."},"method":{"type":"string","enum":["GET","PUT","POST"],"description":"HTTP method to use."},"required":{"type":"boolean","description":"When `true`, this action must be completed before the\napplication can be submitted. Used for submission\nprerequisites like uploading supporting documentation\nor completing payment. Not present on most actions.\n"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"responses":{"BadRequest":{"description":"Malformed or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"Syntactically valid but semantically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications/{id}":{"put":{"summary":"Update application","description":"Full replacement of application state. Partial updates are not supported.\nApplications can only be updated before submission.\n","operationId":"updateApplication","tags":["Applications"],"parameters":[{"$ref":"#/components/parameters/ApplicationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationCreateRequest"}}}},"responses":{"200":{"description":"Application updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Application already pending or effectuated."},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}} ``` ## Get application > Full application record including policy status, payment instructions, and carrier data. ```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"parameters":{"ApplicationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"HealthSherpa application ID."}},"schemas":{"ApplicationResponse":{"type":"object","properties":{"application_id":{"type":"string"},"external_id":{"type":"string"},"tpa_slug":{"type":"string"},"policy_status":{"type":"string","enum":["draft","pending_effectuation","effectuated","submission_failed","cancelled","terminated"],"description":"`draft` when the application has not yet been submitted.\nTransitions to `pending_effectuation` on successful submission.\n`submission_failed` when the asynchronous carrier submission\nfailed after the submit endpoint returned 202. Poll the\napplication to detect this state and check `errors` for details.\n"},"document_status":{"type":"string","enum":["none_needed","required","uploaded","verified","denied"],"description":"SEP document verification status.\n`none_needed`: no documentation required.\n`required`: documentation required but not yet uploaded.\n`uploaded`: documentation uploaded, pending verification.\n`verified`: documentation verified.\n`denied`: documentation denied.\n","nullable":true},"sep_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submitted_at":{"type":"string","format":"date-time","nullable":true},"desired_effective_date":{"type":"string","format":"date"},"plan_hios_id":{"type":"string"},"plan_year":{"type":"integer"},"issuer_hios_id":{"type":"string"},"payment_instructions":{"$ref":"#/components/schemas/PaymentInstructions"},"payment":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/PolicyPaymentStatus"}],"description":"Carrier-reported payment status. Only present after\nsubmission. For carriers that use payment redirect, this\ndata depends on the carrier reporting it back and may not\nbe immediately available.\n"},"policies":{"type":"array","items":{"$ref":"#/components/schemas/PolicyDetail"}},"application":{"type":"object","description":"Echo of the application data as stored."},"errors":{"type":"array","description":"Submission-readiness errors. Present on every POST, PUT, and GET\nresponse. An empty array means the application is ready to submit.\nEach entry uses the same `ErrorDetail` structure as top-level API\nerrors, with `code`, `message`, and optional `field`.\nCarrier-specific required fields (e.g., SSN for most carriers,\nguardian for minor applicants) are enforced dynamically based\non the selected plan's carrier.\n","items":{"$ref":"#/components/schemas/ValidationDetail"}},"next_actions":{"type":"array","description":"State-aware list of actions the partner can take on this\napplication. Changes based on `policy_status`, validation\nstate, and carrier capabilities. Use `rel` to identify\nthe action, `href` for the URL, and `method` for the\nHTTP verb.\n","items":{"$ref":"#/components/schemas/NextAction"}}}},"PaymentInstructions":{"type":"object","description":"Carrier-specific payment guidance.","properties":{"payment_required_with_submission":{"type":"boolean","description":"`true` when payment must be set via\n`PUT /applications/:id/payment_method` before submission.\nCurrently applies to Cigna and Elevance (in-flow).\n"},"payment_redirect_supported":{"type":"boolean","description":"`true` when the carrier supports browser-based payment\nredirect. Use `GET /applications/:id/payment_redirect` to\nretrieve the endpoint URL and form fields.\n"},"pay_by_phone_supported":{"type":"boolean"},"payment_phone_number":{"type":"string","nullable":true}}},"PolicyPaymentStatus":{"type":"object","description":"Carrier-reported payment information. All fields are nullable\nbecause data availability depends on whether the carrier has\nreported payment status. For carriers using payment redirect,\nthis information may not be available until the carrier sends\nan update.\n","properties":{"payment_status":{"type":"string","nullable":true,"description":"Carrier-reported payment state."},"payment_status_updated_date":{"type":"string","format":"date","nullable":true},"grace_period_start_date":{"type":"string","format":"date","nullable":true},"paid_through_date":{"type":"string","format":"date","nullable":true},"past_due_member_responsibility_balance_due":{"type":"string","nullable":true},"current_member_responsibility_balance_due":{"type":"string","nullable":true},"autopay_indicator":{"type":"boolean","nullable":true}}},"PolicyDetail":{"type":"object","properties":{"policy_id":{"type":"string"},"effective_date":{"type":"string","format":"date"},"expiration_date":{"type":"string","format":"date"},"status":{"type":"string","enum":["pending_effectuation","effectuated","cancelled","terminated"]},"plan_hios_id":{"type":"string"},"gross_premium":{"type":"number","format":"float"},"members":{"type":"array","items":{"type":"object","properties":{"member_id":{"type":"string"},"effective_date":{"type":"string","format":"date"},"removed_date":{"type":"string","format":"date","nullable":true}}}},"agent_of_record":{"type":"object","properties":{"npn":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"state_license_number":{"type":"string"},"email":{"type":"string"}}},"payment":{"$ref":"#/components/schemas/PolicyPaymentStatus"}}},"ValidationDetail":{"description":"Alias for ErrorDetail. Validation errors in `errors`\nuse the same structure as top-level API errors.\n","allOf":[{"$ref":"#/components/schemas/ErrorDetail"}]},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}},"NextAction":{"type":"object","description":"A hypermedia action link describing an available operation on the application.","required":["rel","href","method"],"properties":{"rel":{"type":"string","description":"Relation type identifying the action. Possible values:\n`self`, `update`, `validate`, `submit`, `cancel`,\n`terminate`, `payment_redirect`,\n`upload_supporting_documentation`.\n"},"href":{"type":"string","description":"Relative URL for the action."},"method":{"type":"string","enum":["GET","PUT","POST"],"description":"HTTP method to use."},"required":{"type":"boolean","description":"When `true`, this action must be completed before the\napplication can be submitted. Used for submission\nprerequisites like uploading supporting documentation\nor completing payment. Not present on most actions.\n"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications/{id}":{"get":{"summary":"Get application","description":"Full application record including policy status, payment instructions, and carrier data.","operationId":"getApplication","tags":["Applications"],"parameters":[{"$ref":"#/components/parameters/ApplicationId"}],"responses":{"200":{"description":"Application details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` ## Upload supporting documentation > Upload a document to support SEP eligibility. Some carriers require\ > documentation for certain SEP reasons before coverage is effectuated.\ > Use \`GET /applications/{id}\` to check \`document\_status\`.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"parameters":{"ApplicationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"HealthSherpa application ID."}},"schemas":{"SupportingDocumentRequest":{"type":"object","required":["file","document_type"],"properties":{"file":{"type":"object","required":["filename","content_type","content_base64"],"properties":{"filename":{"type":"string"},"content_type":{"type":"string","enum":["application/pdf","image/jpeg","image/png"]},"content_base64":{"type":"string","format":"byte"}}},"document_type":{"type":"string","enum":["sep"],"description":"Type of supporting document. Currently only \"sep\" is accepted."}}},"SupportingDocumentResponse":{"type":"object","properties":{"document_id":{"type":"string"},"application_id":{"type":"string"},"filename":{"type":"string"},"document_type":{"type":"string"},"uploaded_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"Syntactically valid but semantically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications/{id}/supporting_documentation":{"post":{"summary":"Upload supporting documentation","description":"Upload a document to support SEP eligibility. Some carriers require\ndocumentation for certain SEP reasons before coverage is effectuated.\nUse `GET /applications/{id}` to check `document_status`.\n","operationId":"uploadSupportingDocumentation","tags":["Supporting Documentation"],"parameters":[{"$ref":"#/components/parameters/ApplicationId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","document_type"],"properties":{"file":{"type":"string","format":"binary","description":"The document file (PDF, JPEG, or PNG)."},"document_type":{"type":"string","enum":["sep"],"description":"Type of supporting document being uploaded. Currently only \"sep\" is accepted."}}}},"application/json":{"schema":{"$ref":"#/components/schemas/SupportingDocumentRequest"}}}},"responses":{"201":{"description":"Document uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportingDocumentResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}} ``` ## Submit application > Submits the application to the carrier. Transitions to \`pending\_effectuation\`.\ > Application becomes read-only after submission. Check \`errors\`\ > on the application response before calling. Submission will fail with\ > 422 if there are outstanding errors.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"parameters":{"ApplicationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"HealthSherpa application ID."}},"schemas":{"SubmitResponse":{"type":"object","properties":{"application_id":{"type":"string"},"external_id":{"type":"string"},"plan_year":{"type":"integer"},"plan_hios_id":{"type":"string"},"policy_status":{"type":"string"},"payment_instructions":{"$ref":"#/components/schemas/PaymentInstructions"},"submitted_at":{"type":"string","format":"date-time"}}},"PaymentInstructions":{"type":"object","description":"Carrier-specific payment guidance.","properties":{"payment_required_with_submission":{"type":"boolean","description":"`true` when payment must be set via\n`PUT /applications/:id/payment_method` before submission.\nCurrently applies to Cigna and Elevance (in-flow).\n"},"payment_redirect_supported":{"type":"boolean","description":"`true` when the carrier supports browser-based payment\nredirect. Use `GET /applications/:id/payment_redirect` to\nretrieve the endpoint URL and form fields.\n"},"pay_by_phone_supported":{"type":"boolean"},"payment_phone_number":{"type":"string","nullable":true}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications/{id}/submit":{"post":{"summary":"Submit application","description":"Submits the application to the carrier. Transitions to `pending_effectuation`.\nApplication becomes read-only after submission. Check `errors`\non the application response before calling. Submission will fail with\n422 if there are outstanding errors.\n","operationId":"submitApplication","tags":["Application Actions"],"parameters":[{"$ref":"#/components/parameters/ApplicationId"}],"responses":{"200":{"description":"Application submitted, now pending effectuation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Not submittable or fails validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Get payment redirect data > Returns the data needed to redirect the user to the carrier's\ > payment page. The response includes the carrier endpoint URL,\ > the HTTP method, and a set of form fields to include in the\ > request.\ > \ > The keys and values in \`fields\` will vary depending on the\ > carrier's payment integration. Your platform does not need to\ > interpret or understand them. Include every returned field\ > exactly as provided. Build a form POST to the returned\ > \`endpoint\` with the returned \`fields\` as hidden inputs and\ > submit it in the user's browser.\ > \ > This is the primary payment path for most off-exchange carriers.\ > Check \`payment\_instructions.payment\_redirect\_supported\` on the\ > application response to determine if this endpoint applies.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"parameters":{"ApplicationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"HealthSherpa application ID."}},"schemas":{"PaymentRedirectResponse":{"type":"object","properties":{"application_id":{"type":"string"},"method":{"type":"string","description":"HTTP method to use. Always `POST`.","enum":["POST"]},"endpoint":{"type":"string","format":"uri","description":"The carrier's payment URL. Submit the form POST to this URL."},"fields":{"type":"array","description":"Form fields to include as hidden inputs in the POST to\n`endpoint`. Each entry has a `name` and `value`. The\nfields will vary depending on the carrier's payment\nintegration. Include every returned field exactly as\nprovided; do not filter, rename, or modify any entries.\n","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","description":"The form field name."},"value":{"type":"string","description":"The form field value."}}}}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications/{id}/payment_redirect":{"get":{"summary":"Get payment redirect data","description":"Returns the data needed to redirect the user to the carrier's\npayment page. The response includes the carrier endpoint URL,\nthe HTTP method, and a set of form fields to include in the\nrequest.\n\nThe keys and values in `fields` will vary depending on the\ncarrier's payment integration. Your platform does not need to\ninterpret or understand them. Include every returned field\nexactly as provided. Build a form POST to the returned\n`endpoint` with the returned `fields` as hidden inputs and\nsubmit it in the user's browser.\n\nThis is the primary payment path for most off-exchange carriers.\nCheck `payment_instructions.payment_redirect_supported` on the\napplication response to determine if this endpoint applies.\n","operationId":"getPaymentRedirect","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/ApplicationId"}],"responses":{"200":{"description":"Payment redirect data returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRedirectResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Payment redirect not supported for this carrier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## List applications > Paginated list of applications. Supports filtering by status, plan, and timestamps.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"schemas":{"ApplicationListResponse":{"type":"object","properties":{"applications":{"type":"array","items":{"type":"object","properties":{"application_id":{"type":"string"},"external_id":{"type":"string"},"employer_external_id":{"type":"string"},"plan_year":{"type":"string"},"plan_hios_id":{"type":"string"},"exchange_type":{"type":"string"},"policy_status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}}}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications":{"get":{"summary":"List applications","description":"Paginated list of applications. Supports filtering by status, plan, and timestamps.\n","operationId":"listApplications","tags":["Applications"],"parameters":[{"name":"policy_status","in":"query","schema":{"type":"string","enum":["draft","pending_effectuation","effectuated","submission_failed","cancelled","terminated"]}},{"name":"external_id","in":"query","schema":{"type":"string"}},{"name":"plan_year","in":"query","schema":{"type":"integer"}},{"name":"issuer_hios_id","in":"query","schema":{"type":"string"}},{"name":"plan_hios_id","in":"query","schema":{"type":"string"}},{"name":"employer_external_id","in":"query","schema":{"type":"string"},"description":"Filter by the employer's external identifier."},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601. Returns applications updated after this time."},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"List of applications","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel application > Cancels an application that is pending effectuation.\ > Not all carriers support cancellation. Use the \`GET /applications/{id}\`\ > response to check carrier capabilities.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"parameters":{"ApplicationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"HealthSherpa application ID."}},"schemas":{"StatusChangeResponse":{"type":"object","properties":{"application_id":{"type":"string"},"policy_status":{"type":"string"},"effective_date":{"type":"string","format":"date","description":"The effective date of the status change (cancellation or termination).","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications/{id}/cancel":{"post":{"summary":"Cancel application","description":"Cancels an application that is pending effectuation.\nNot all carriers support cancellation. Use the `GET /applications/{id}`\nresponse to check carrier capabilities.\n","operationId":"cancelApplication","tags":["Application Actions"],"parameters":[{"$ref":"#/components/parameters/ApplicationId"}],"responses":{"202":{"description":"Cancellation request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChangeResponse"}}}},"400":{"description":"Cancellation not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` ## Terminate policy > Terminates an active (effectuated) policy. Used when coverage should end\ > before the natural expiration date.
```json {"openapi":"3.0.0","info":{"title":"EnrollConnect API","version":"0.1.0-preview"},"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key provided during onboarding."}},"parameters":{"ApplicationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"HealthSherpa application ID."}},"schemas":{"StatusChangeResponse":{"type":"object","properties":{"application_id":{"type":"string"},"policy_status":{"type":"string"},"effective_date":{"type":"string","format":"date","description":"The effective date of the status change (cancellation or termination).","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"All error responses return a top-level `errors` array. Each entry\ncontains a machine-readable `code`, a human-readable `message`, and\nan optional `field` dot-path when the error is tied to a specific\nrequest field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Consumers should switch on this value\nrather than parsing `message` strings.\n","enum":["unauthorized","token_expired","forbidden","not_found","plan_not_found","plan_not_available","missing_required_field","invalid_field_value","invalid_field_format","internal_error","rate_limit_exceeded"]},"field":{"type":"string","description":"Dot-path to the offending field in the request body. Only present\nfor field-level validation errors; omitted for auth, system, and\nresource-level errors.\n"},"message":{"type":"string","description":"Human-readable description of the error. May change over time;\nconsumers should not rely on exact wording.\n"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/applications/{id}/terminate":{"post":{"summary":"Terminate policy","description":"Terminates an active (effectuated) policy. Used when coverage should end\nbefore the natural expiration date.\n","operationId":"terminateApplication","tags":["Application Actions"],"parameters":[{"$ref":"#/components/parameters/ApplicationId"}],"responses":{"202":{"description":"Termination request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChangeResponse"}}}},"400":{"description":"Termination not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ichra.healthsherpa.com/api-reference/endpoints/enrollconnect-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.