---
title: "Create application"
method: POST
path: "/api/v1/applications"
tags: ["Applications"]
---

# Create application

`POST /api/v1/applications`

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

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

## Request body

- ApplicationCreateRequest — Canonical application schema. This schema is shared between the EnrollConnect API (`POST /api/v1/applications`) and the Application Deeplink (`POST /public/ichra/off_ex`). Build your payload once and send it to either endpoint.
  - `external_id` string — Your unique identifier for this application.
  - `_agent_id` string, nullable — HealthSherpa-provided agent identifier (slug). Optional for API. When provided, the application appears under this agent's book of business in HealthSherpa. When omitted, the agent defaults to the one associated with your platform account. Required for deeplink.
  - `tpa_slug` string — HealthSherpa-assigned TPA identifier (provided during onboarding).
  - `plan_hios_id` string, required — 14-character HIOS plan ID.
  - `plan_year` integer, required
  - `dental_plan_hios_id` string, nullable — HIOS ID of a qualified stand-alone dental plan. Used by HCSC (Blue Cross Blue Shield of IL, MT, NM, OK, TX) plans that require pediatric dental coverage. Provide this **or** `attestations.pediatric_dental` — exactly one must be present, not both.
  - `desired_effective_date` string, date — Optional. When omitted, the carrier auto-determines the effective date based on the SEP type and event date (recommended). When provided, the date must be one of the carrier's valid effective dates for the given SEP reason and event date. If the date is invalid, the API returns a 422 with either the list of valid dates to choose from, or a message indicating that effective date selection is not available for the given enrollment parameters (meaning the carrier does not allow date selection for this SEP type). There is no endpoint to query valid dates ahead of time.
  - `agent_of_record` AgentOfRecord
    - `first_name` string
    - `last_name` string
    - `national_producer_number` string — 1-10 digits, must not start with 0.
    - `carrier_producer_code` string — Carrier-specific agent identifier. For Elevance, this is the 10-character uppercase string they generate (ends in Y or Z).
    - `state_license_number` string
    - `email` string, email
    - `phone` string
    - `fax_number` string
    - `address` SimpleAddress
      - `street_address_1` string
      - `street_address_2` string
      - `city` string
      - `state` string
      - `zip_code` string
    - `signature` string
  - `applicants` Applicants, required
    - `primary` PrimaryApplicant, required
      - `member_id` string, nullable — Stable HealthSherpa identifier for this applicant on an existing application. Returned on `GET` application responses for the primary and dependent applicants. On `PUT /api/v1/applications/{id}`, include the `member_id` from a prior response to update that applicant in place. Not expected on `POST /api/v1/applications` (create); it is ignored if sent.
      - `first_name` string, required
      - `middle_name` string
      - `last_name` string, required
      - `suffix` 'Jr.' | 'Sr.' | 'II' | 'III' | 'IV' | 'V'
      - `ssn` string — 9 digits, no dashes. Encrypted at rest.
      - `itin` string — Individual Taxpayer Identification Number. Alternative to SSN.
      - `date_of_birth` string, date, required
      - `gender` 'male' | 'female', required — Most states accept `male`/`female`. NY also accepts `x`.
      - `married` boolean
      - `us_citizen` boolean
      - `resides_in_state` boolean
      - `uses_tobacco` boolean — Tobacco use in the last 6 months.
      - `tobacco_not_applicable` boolean — Set to `true` if tobacco question is not applicable for this applicant.
      - `race_ethnicity` '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' — Required by some carriers. Use "decline_to_answer" if not collected.
      - `hispanic_origin` 'yes' | 'no' | 'decline_to_answer' — Required by some carriers. Use "decline_to_answer" if not collected.
      - `hispanic_origin_description` 'cuban' | 'mexican_mexican_american_or_chicanx' | 'puerto_rican' | 'other_hispanic_latino_or_spanish_origin' | 'decline_to_answer' — Required when hispanic_origin is "yes".
      - `language_spoken` 'english' | 'spanish' | 'arabic' | 'chinese' | 'french_creole' | 'french' | 'german' | 'gujarati' | 'hindi' | 'korean' | 'polish' | 'portuguese' | 'russian' | 'tagalog' | 'urdu' | 'vietnamese' | 'other'
      - `language_written` 'english' | 'spanish' | 'arabic' | 'chinese' | 'french_creole' | 'french' | 'german' | 'gujarati' | 'hindi' | 'korean' | 'polish' | 'portuguese' | 'russian' | 'tagalog' | 'urdu' | 'vietnamese' | 'other'
      - `external_id` string — Your identifier for this member.
      - `email` string, email
      - `phone` string
      - `phone_type` 'home' | 'cell' | 'work' — Type of phone number provided. Required only for carriers that collect it; when present, must be one of `home`, `cell`, `work` (invalid values are rejected with a validation error). Carriers that require `phone_type` and the values they accept: - HCSC (BCBS IL/MT/NM/OK/TX): `cell`, `home` - BCBS Michigan: `home`, `cell`, `work` - Mountain Health CO-OP: `home`, `cell`, `work` - Oscar: `home`, `cell`, `work` - Sanford Health: `home`, `cell`, `work` - Security Health Plan: `home`, `cell`
      - `secondary_phone` string — Secondary contact phone number.
      - `full_time_student` boolean
      - `graduation_date` string, date — Required if `full_time_student` is `true`.
      - `marital_status` 'single' | 'married' | 'domestic_partner' — Snake-case marital status. When provided, takes precedence over the `married` boolean and is validated for consistency with it. Required by carriers that collect this field; discarded on ingest by carriers that do not. Per-carrier acceptance: - Cigna, Oscar, CareSource, Sanford: `single`, `married` - Anthem, Wellpoint: additionally accept `domestic_partner` - Default configuration does not collect this field and ignores any value Use `GET /plans/:hios_id?include=enrollment_requirements` to retrieve the available options per carrier/state.
      - `has_disability` boolean — Affects dependent age eligibility limits.
      - `disability_is_temporary` boolean — Whether the disability is temporary. Only accepted by carriers that require disability follow-up questions.
      - `disability_end_date` string, date — Expected end date of a temporary disability. Only accepted by carriers that require disability follow-up questions.
      - `medicare_medicaid_eligible` boolean — Whether the applicant is eligible for Medicare or Medicaid. Only accepted by carriers that require this field.
      - `medicare_eligible` boolean — Whether the applicant is eligible for Medicare.
      - `enrolled_in_medicare` boolean
      - `enrolled_in_medicare_parts_a_or_b` boolean
      - `enrolled_in_medicaid_chip_or_other_gov_program` boolean
      - `veteran_or_active_duty_military` boolean
      - `currently_incarcerated` boolean
      - `has_eligible_immigration_status` boolean
      - `existing_coverage` ExistingCoverage
        - `has_existing_coverage` boolean
        - `plan_replaces_existing_coverage` boolean
        - `type` 'issuer' | 'government' — `issuer`: coverage with another issuer. `government`: government program (Medicare, Medicaid, etc.).
        - `insurer` string
        - `policy_id` string
        - `policyholder_name` string
        - `start_date` string, date
        - `term_date` string, date
        - `will_continue` boolean — Whether the existing coverage will continue alongside the new plan.
      - `guardian` Guardian — Required for primary applicants under 18.
        - `first_name` string
        - `middle_name` string
        - `last_name` string
        - `suffix` 'Jr.' | 'Sr.' | 'II' | 'III' | 'IV' | 'V'
        - `gender` 'male' | 'female'
        - `relationship` 'parent' | 'legal_guardian' | 'grandparent' | 'other'
        - `date_of_birth` string, date
        - `relationship_other` string — Required if `relationship` is `other`.
        - `email` string, email
        - `home_phone` string
        - `alternate_phone` string
        - `mailing_address` object — Guardian's mailing address, if different from the applicant's residential address.
          - `street_address_1` string
          - `street_address_2` string
          - `city` string
          - `state` string
          - `zip_code` string
          - `fips_code` string
      - `responsible_party` ResponsibleParty — Responsible party for a minor applicant, when someone other than the guardian is financially responsible. Required by Security Health, Sanford, Oscar, and UHC.
        - `first_name` string
        - `middle_name` string
        - `last_name` string
        - `date_of_birth` string, date
        - `sex` 'male' | 'female'
        - `relationship` 'parent_guardian' | 'sibling'
        - `phone` string
        - `street_address_1` string
        - `street_address_2` string
        - `city` string
        - `state` string
        - `zip_code` string
      - `translator` Translator — Translator assisting the applicant. Required by some carriers when the applicant requires language assistance.
        - `first_name` string
        - `middle_name` string
        - `last_name` string
        - `reason` string — Why a translator is needed.
      - `signature` string — 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` boolean
      - `has_pediatric_dental_coverage` boolean
      - `previously_applied` boolean
      - `previously_applied_member_id` string
      - `primary_requesting_coverage` boolean — Whether the primary applicant is requesting coverage for themselves.
      - `add_to_donate_life_registry` boolean — Whether the applicant wants to be added to the Donate Life registry. Only accepted by carriers that support this field.
    - `dependents` Dependent[]
      - `member_id` string, nullable — Stable HealthSherpa identifier for this dependent on an existing application. Returned on `GET` application responses. On `PUT /api/v1/applications/{id}`, include the `member_id` from a prior response to update this dependent in place; omit it to add a new dependent. Not expected on `POST /api/v1/applications` (create); it is ignored if sent.
      - `first_name` string, required
      - `middle_name` string
      - `last_name` string, required
      - `suffix` 'Jr.' | 'Sr.' | 'II' | 'III' | 'IV' | 'V'
      - `ssn` string
      - `itin` string — Individual Taxpayer Identification Number. Alternative to SSN.
      - `date_of_birth` string, date, required
      - `gender` 'male' | 'female', required
      - `relationship` 'spouse' | 'domestic_partner' | 'child' | 'parent' | 'stepparent' | 'parent_in_law' | 'other', required — Relationship of this dependent to the primary applicant. Accepted values are carrier- and state-specific: the API validates against the resolved carrier configuration and returns `invalid_field_value` when a value isn't accepted for that carrier/state. Broadly supported: `spouse`, `domestic_partner`, `child`. Some carriers narrow this further (e.g. Cigna, Sanford, and BCBS SC accept only `spouse` and `child`). Gated values: - `parent` / `stepparent`: default carriers in IL or CA for plan year 2026+; HCSC (bcbs-inmot) in IL for 2026+; Anthem in CA for 2026+. Ambetter (CA) and Western Health Advantage (CA) accept `parent` only. - `parent_in_law` / `other`: Anthem in CA, plan year 2026+ only.
      - `married` boolean
      - `us_citizen` boolean
      - `resides_in_state` boolean
      - `uses_tobacco` boolean
      - `tobacco_not_applicable` boolean — Set to `true` if tobacco question is not applicable for this applicant.
      - `race_ethnicity` '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' — Required by some carriers. Use "decline_to_answer" if not collected.
      - `hispanic_origin` 'yes' | 'no' | 'decline_to_answer' — Required by some carriers. Use "decline_to_answer" if not collected.
      - `hispanic_origin_description` 'cuban' | 'mexican_mexican_american_or_chicanx' | 'puerto_rican' | 'other_hispanic_latino_or_spanish_origin' | 'decline_to_answer' — Required when hispanic_origin is "yes".
      - `language_spoken` 'english' | 'spanish' | 'arabic' | 'chinese' | 'french_creole' | 'french' | 'german' | 'gujarati' | 'hindi' | 'korean' | 'polish' | 'portuguese' | 'russian' | 'tagalog' | 'urdu' | 'vietnamese' | 'other'
      - `language_written` 'english' | 'spanish' | 'arabic' | 'chinese' | 'french_creole' | 'french' | 'german' | 'gujarati' | 'hindi' | 'korean' | 'polish' | 'portuguese' | 'russian' | 'tagalog' | 'urdu' | 'vietnamese' | 'other'
      - `email` string, email
      - `phone` string
      - `external_id` string — Your identifier for this member.
      - `full_time_student` boolean
      - `graduation_date` string, date — Required if `full_time_student` is `true`.
      - `marital_status` 'single' | 'married' | 'domestic_partner' — Snake-case marital status. When provided, takes precedence over the `married` boolean and is validated for consistency with it. Required by carriers that collect this field; discarded on ingest by carriers that do not. Per-carrier acceptance: - Cigna, Oscar, CareSource, Sanford: `single`, `married` - Anthem, Wellpoint: additionally accept `domestic_partner` - Default configuration does not collect this field and ignores any value Use `GET /plans/:hios_id?include=enrollment_requirements` to retrieve the available options per carrier/state.
      - `has_disability` boolean — Affects dependent age eligibility limits.
      - `disability_is_temporary` boolean — Whether the disability is temporary. Only accepted by carriers that require disability follow-up questions.
      - `disability_end_date` string, date — Expected end date of a temporary disability. Only accepted by carriers that require disability follow-up questions.
      - `medicare_medicaid_eligible` boolean — Whether the applicant is eligible for Medicare or Medicaid. Only accepted by carriers that require this field.
      - `medicare_eligible` boolean
      - `enrolled_in_medicare` boolean
      - `enrolled_in_medicare_parts_a_or_b` boolean
      - `enrolled_in_medicaid_chip_or_other_gov_program` boolean
      - `veteran_or_active_duty_military` boolean
      - `currently_incarcerated` boolean
      - `has_eligible_immigration_status` boolean
      - `add_to_donate_life_registry` boolean — Whether the applicant wants to be added to the Donate Life registry. Only accepted by carriers that support this field.
      - `existing_coverage` ExistingCoverage
        - `has_existing_coverage` boolean
        - `plan_replaces_existing_coverage` boolean
        - `type` 'issuer' | 'government' — `issuer`: coverage with another issuer. `government`: government program (Medicare, Medicaid, etc.).
        - `insurer` string
        - `policy_id` string
        - `policyholder_name` string
        - `start_date` string, date
        - `term_date` string, date
        - `will_continue` boolean — Whether the existing coverage will continue alongside the new plan.
      - `alternate_address` AlternateAddress — Address for a dependent living at a different address than the primary applicant.
        - `street_address_1` string
        - `street_address_2` string
        - `city` string
        - `state` string
        - `zip_code` string
        - `fips_code` string
        - `reason` string — Reason the dependent has a different address.
      - `guardian` Guardian — Required for primary applicants under 18.
        - `first_name` string
        - `middle_name` string
        - `last_name` string
        - `suffix` 'Jr.' | 'Sr.' | 'II' | 'III' | 'IV' | 'V'
        - `gender` 'male' | 'female'
        - `relationship` 'parent' | 'legal_guardian' | 'grandparent' | 'other'
        - `date_of_birth` string, date
        - `relationship_other` string — Required if `relationship` is `other`.
        - `email` string, email
        - `home_phone` string
        - `alternate_phone` string
        - `mailing_address` object — Guardian's mailing address, if different from the applicant's residential address.
          - `street_address_1` string
          - `street_address_2` string
          - `city` string
          - `state` string
          - `zip_code` string
          - `fips_code` string
  - `residential_address` object, required — Residential address used to validate that the selected plan is available in the applicant's county.
    - `street_address_1` string, required
    - `street_address_2` string
    - `city` string, required
    - `state` string, required — Two-letter state code.
    - `zip_code` string, required
    - `fips_code` string, required — 5-digit FIPS county code. See [FIPS County Codes](https://docs.ichra.healthsherpa.com/api-reference/supporting-material/fips-county-codes).
  - `mailing_address` MailingAddress
    - `street_address_1` string, required
    - `street_address_2` string
    - `city` string, required
    - `state` string, required — Two-letter state code.
    - `zip_code` string, required
    - `fips_code` string — 5-digit FIPS county code. See [FIPS County Codes](https://docs.ichra.healthsherpa.com/api-reference/supporting-material/fips-county-codes).
    - `different_from_home_address` boolean
    - `billing_use_only` boolean
  - `hra` HRA — Health Reimbursement Arrangement details. Applies to the primary applicant (the employee receiving the HRA offer). If the ICHRA is affordable, all household members are ineligible for premium tax credits.
    - `offered_hra` boolean, nullable — `true`: applicant is offered an HRA. `false`: applicant is not offered an HRA. `null`: unknown.
    - `type` 'ichra' | 'qsehra'
    - `amount` number, float — Monthly contribution in USD.
    - `contribution_covers` 'premium' | 'premium_oop' — `premium`: premiums only. `premium_oop`: premiums and out-of-pocket costs.
    - `used_for_spousal_or_family_premiums` 'true' | 'false' | 'unknown' — Whether the HRA is used for spousal or family premiums. Relevant for QSEHRA 834 indicators.
    - `start` string, date
    - `employer` Employer
      - `name` string
      - `external_id` string — Your identifier for this employer group.
      - `phone` string
      - `fein` string — 9-digit Federal Employer Identification Number.
      - `address` Address
        - `street_address_1` string, required
        - `street_address_2` string
        - `city` string, required
        - `state` string, required — Two-letter state code.
        - `zip_code` string, required
        - `fips_code` string — 5-digit FIPS county code. See [FIPS County Codes](https://docs.ichra.healthsherpa.com/api-reference/supporting-material/fips-county-codes).
    - `premium_payer` string
    - `household_size` integer
    - `annual_household_income` number, float
    - `annual_household_income_determination` string
  - `special_enrollment_period` SpecialEnrollmentPeriod
    - `event_type` 'birth' | 'adoption' | 'death' | 'divorce' | 'marriage' | 'domestic_partnership' | 'child_support' | 'loss_of_mec' | 'loss_of_dependent' | 'removing_dependent' | 'dependent_lost_coverage' | 'loss_of_pregnancy_coverage' | 'loss_of_medicaid_chip' | 'loss_of_medicaid_or_public_program_eligibility' | 'loss_of_cobra' | 'end_of_non_calendar_year_policy' | 'change_in_household_status' | 'lost_aptc' | 'at_or_below_150_fpl' | 'gained_aptc' | 'new_aptc_eligibility_from_esc' | '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' | 'discontinues_coverage' | 'ihcia' | 'gained_status' | 'exchange_staff_errors' | 'other' — Qualifying event types accepted across supported carriers. Before collecting or sending a value, call `GET /api/v1/plans/{hios_id}?plan_year=YYYY&include=enrollment_requirements` and use a key returned in `plan.enrollment_requirements.special_enrollment_period.event_types`. Each event type includes its allowed date window and whether supporting documentation is required. Sending a value that is not returned for the selected plan and plan year returns 422. For ICHRA enrollments, `offered_ichra` is the most common reason.
    - `event_date` string, date
  - `attestations` Attestations
    - `agrees_issuer_attestations` boolean
    - `broker_signature_attestation` boolean
    - `electronic_signature_consent` boolean
    - `disclosure_statement_accepted` boolean — Acceptance of a carrier consumer-choice disclosure. **Upcoming:** will be required for **Texas HMO** plans — submission is rejected with `{ field: "disclosure_statement_accepted", code: "missing_required_field" }` when the plan requires the disclosure and this is not `true`. The disclosure label text is returned as `attestations.disclosure_statement_checkbox_label` (and the TX HMO payload as `attestations.tx_hmo_consumer_choice_disclosure`) on `GET /plans/:hios_id?include=enrollment_requirements`.
    - `coverage_replacement_attestation_accepted` boolean
    - `pediatric_dental` 'purchased_separately' | 'not_applicable' — Pediatric dental attestation for HCSC (BCBS IL/MT/NM/OK/TX) plans that require pediatric dental coverage. `purchased_separately`: pediatric dental purchased via a stand-alone dental plan. `not_applicable`: no children under 19 on the application. Provide this **or** the top-level `dental_plan_hios_id` — exactly one must be present, not both. Submit the enum key here; the consumer-facing label to display comes from the `{value: label}` map at `enrollment_requirements.attestations.pediatric_dental.options` on the plan-lookup response (do not display the raw key).
    - `agent_submitted_application` boolean
    - `agent_provided_consumer_marketing_materials` boolean
    - `agent_advised_consumer_of_product_features` boolean
    - `agent_retained_signed_application_copy` boolean
    - `consumer_working_with_agent` boolean
    - `spouse_or_dependent_authorization` boolean — Authorization for dependents/spouse to be included on the application.
  - `signatures` Signatures
    - `signature_date` string, date — Date the application was signed. Required for submission. This is separate from applicants.primary.signature (the typed name).
    - `pediatric_dental_signature` string
    - `pediatric_dental_signature_date` string, date, nullable
    - `translator_signature_date` string, date, nullable
    - `state_supplement_primary_signature` string — State-required supplemental form signature (primary applicant). Required for CO, UT, NJ.
    - `state_supplement_spouse_signature` string — State-required supplemental form signature (spouse). Required for UT.
    - `state_supplement_disclosures_signature` string — State-required supplemental form disclosures signature (primary applicant). Required for CO.
  - `communication_preferences` CommunicationPreferences
    - `application_notification_email` boolean
    - `application_notification_call` boolean
    - `application_notification_text` boolean
    - `email_contact_consent` boolean
    - `marketing_contact_consent` boolean
    - `decline_marketing_contact` boolean
    - `preferred_communication_method` 'email' | 'phone' | 'mail'
    - `agrees_hsa_contact_opt_in` boolean
    - `communication_preference_affirmed` boolean — Whether the applicant has affirmed their communication preferences.
  - `american_indian_or_alaskan_native_in_household` boolean
  - `analytics` Analytics — Optional tracking and attribution parameters.
    - `utm_source` string
    - `utm_medium` string
    - `utm_campaign` string
    - `utm_term` string
    - `utm_content` string

## Response `201`

Application created

- ApplicationResponse
  - `application_id` string
  - `external_id` string
  - `tpa_slug` string
  - `policy_status` 'draft' | 'pending_effectuation' | 'effectuated' | 'submission_failed' | 'cancelled' | 'terminated' — `draft` when the application has not yet been submitted. Transitions to `pending_effectuation` on successful submission. `submission_failed` when the asynchronous carrier submission failed after the submit endpoint returned 202. Poll the application to detect this state and check `errors` for details.
  - `document_status` 'none_needed' | 'required' | 'uploaded' | 'verified' | 'denied', nullable — SEP document verification status. Transitions are driven by carrier responses and document uploads. `none_needed`: no documentation required for this SEP type. `required`: documentation required but not yet uploaded. Upload via `POST /applications/:id/supporting_documentation`. `uploaded`: documentation uploaded and sent to carrier, pending verification. `verified`: carrier has verified the documentation. `denied`: carrier denied the documentation; the application may be suspended. Status may also change if the carrier initiates a document review after submission (e.g., SEP suspension). Poll the application or subscribe to webhooks to detect transitions.
  - `sep_reason` string, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `submitted_at` string, date-time, nullable
  - `desired_effective_date` string, date
  - `plan_hios_id` string
  - `plan_year` integer
  - `issuer_hios_id` string
  - `payment_instructions` PaymentInstructions — Carrier-specific payment guidance.
    - `payment_required_with_submission` boolean — `true` when payment must be set via `PUT /applications/:id/payment_method` before submission. Currently applies to Cigna and Elevance (in-flow).
    - `payment_redirect_supported` boolean — `true` when the carrier supports browser-based payment redirect. Use `GET /applications/:id/payment_redirect` to retrieve the endpoint URL and form fields.
    - `pay_by_phone_supported` boolean
    - `payment_phone_number` string, nullable
  - `payment` PolicyPaymentStatus — Carrier-reported payment information. All fields are nullable because data availability depends on whether the carrier has reported payment status. For carriers using payment redirect, this information may not be available until the carrier sends an update.
    - `payment_status` string, nullable — Carrier-reported payment state.
    - `payment_status_updated_date` string, date, nullable
    - `grace_period_start_date` string, date, nullable
    - `paid_through_date` string, date, nullable
    - `past_due_member_responsibility_balance_due` string, nullable
    - `current_member_responsibility_balance_due` string, nullable
    - `autopay_indicator` boolean, nullable
  - `policies` PolicyDetail[]
    - `policy_id` string
    - `effective_date` string, date
    - `expiration_date` string, date
    - `status` 'pending_effectuation' | 'effectuated' | 'cancelled' | 'terminated'
    - `plan_hios_id` string
    - `gross_premium` number, float
    - `members` object[]
      - `member_id` string
      - `effective_date` string, date
      - `removed_date` string, date, nullable
    - `agent_of_record` object
      - `npn` string
      - `first_name` string
      - `last_name` string
      - `state_license_number` string
      - `email` string
    - `payment` PolicyPaymentStatus — Carrier-reported payment information. All fields are nullable because data availability depends on whether the carrier has reported payment status. For carriers using payment redirect, this information may not be available until the carrier sends an update.
      - `payment_status` string, nullable — Carrier-reported payment state.
      - `payment_status_updated_date` string, date, nullable
      - `grace_period_start_date` string, date, nullable
      - `paid_through_date` string, date, nullable
      - `past_due_member_responsibility_balance_due` string, nullable
      - `current_member_responsibility_balance_due` string, nullable
      - `autopay_indicator` boolean, nullable
  - `application` object — Echo of the application data as stored.
  - `supports_changes` boolean — Whether the carrier supports post-enrollment changes for this application. Only present on submitted applications.
  - `can_change_plan` boolean — Whether a plan change is currently allowed (based on carrier support, OEP/SEP eligibility, and active policy). Only present on submitted applications.
  - `can_report_change` boolean — Whether demographic changes can be reported (based on carrier support and policy expiration). Only present on submitted applications.
  - `errors` ValidationDetail[] — Submission-readiness errors. Present on every POST, PUT, and GET response. An empty array means the application is ready to submit. Each entry uses the same `ErrorDetail` structure as top-level API errors, with `code`, `message`, and optional `field`. Carrier-specific required fields (e.g., SSN for most carriers, guardian for minor applicants) are enforced dynamically based on the selected plan's carrier.
    - `code` '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' | 'payload_too_large' | 'duplicate_external_id' | 'latest_submission_failed' | 'supporting_documentation_required' | 'ineligible_for_enrollment', required — Machine-readable error code. Consumers should switch on this value rather than parsing `message` strings.
    - `field` string — Dot-path to the offending field in the request body. Only present for field-level validation errors; omitted for auth, system, and resource-level errors.
    - `message` string, required — Human-readable description of the error. May change over time; consumers should not rely on exact wording.
  - `next_actions` NextAction[] — State-aware list of actions the partner can take on this application. Changes based on `policy_status`, validation state, and carrier capabilities. Use `rel` to identify the action, `href` for the URL, and `method` for the HTTP verb.
    - `rel` string, required — Relation type identifying the action. Possible values: `self`, `update`, `validate`, `submit`, `cancel`, `terminate`, `payment_redirect`, `payment_method`, `upload_supporting_documentation`, `change_plan`. For submitted applications with post-enrollment changes enabled, `update`, `change_plan`, and `submit` appear dynamically based on carrier support, enrollment period eligibility, and whether untracked changes exist. If an action is absent, the operation is not permitted for the current application state.
    - `href` string, required — Relative URL for the action.
    - `method` 'GET' | 'PUT' | 'POST', required — HTTP method to use.
    - `required` boolean — When `true`, this action must be completed before the application can be submitted. Used for submission prerequisites like uploading supporting documentation or completing payment. Not present on most actions.
  - `events` ApplicationEvent[] — Audit timeline of the application's lifecycle. Included by default on GET responses for submitted applications. Each event has a `type`, `occurred_at` timestamp, and type-specific fields. Events are ordered newest-first (descending by occurred_at). Maximum 50 events returned. Omitted when `include_events=false` is passed as a query parameter.
    - `type` 'submitted' | 'changed' | 'document_status_changed' | 'cancelled' | 'submission_failed' | 'policy_status_updated', required — `submitted` — carrier submission event. `changed` — tracked field change on the application or applicant. `document_status_changed` — SEP document status transition. `cancelled` — application was cancelled. `submission_failed` — carrier submission failed. `policy_status_updated` — policy status changed.
    - `occurred_at` string, date-time, required
    - `target` 'application' | 'applicant' — For `changed` events: whether the change was on the application or an applicant record.
    - `member_id` string — For `changed` events on an applicant: the member_id of the affected applicant.
    - `changes` object[] — For `changed` events: list of field-level changes. Sensitive fields (SSN, ITIN) are redacted. Only safe fields (name, address, email, phone, plan ID, SEP, DOB, gender, tobacco) show real from/to values.
      - `field` string
      - `from` string, nullable
      - `to` string, nullable
    - `response_code` string — For `submitted` events: carrier response code.
    - `carrier_id` string — For `submitted` events: carrier identifier.
    - `old_status` string — For `document_status_changed` and `policy_status_updated` events.
    - `new_status` string — For `document_status_changed` and `policy_status_updated` events.
    - `policy_id` string — For `policy_status_updated` events.
    - `effective_date` string, date — For `cancelled` events.
    - `message` string — For `submission_failed` events: sanitized error message.

## Other responses

- `401` — Unauthorized - Invalid, missing, or expired OAuth token
- `422` — The request was well-formed but could not be processed

---

[API](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api.md) · [All operations](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/healthsherpa/health-insurance-quotes-api/revisions/3cbfff4e5929/schema)