Deeplinks V2 API Specification

Coming Soon — This specification is in active development and subject to change. Schemas, field names, and endpoint behavior may be revised before general availability.

---

Overview

The Application Deeplink V2 accepts the full canonical enrollment schema — the same request body used by the EnrollConnect API. The key difference: the deeplink returns an HTTP 302 redirect to the HealthSherpa-hosted enrollment UI, where the user completes the application with all provided fields prefilled.

For migration details, structural changes from V1, and field-by-field breakdowns, see the Deeplinks V2 Guide.

The request body is the same canonical schema as the EnrollConnect API, with the addition of skip (deeplink-specific). All fields beyond the required four (plan_hios_id, plan_year, applicants.primary, residential_address) are optional — the more you prefill, the less the agent needs to complete in the HealthSherpa UI.

---

Base URLs

Environment	Base URL
Staging	https://staging.healthsherpa.com
Production	https://www.healthsherpa.com

Authentication uses the x-api-key header (optional in production, required in staging).

---

API Specification

Create prefilled application and redirect

post

Accepts the canonical application schema and redirects the user to the HealthSherpa-hosted enrollment UI with all provided fields prefilled.

This endpoint must be called from your backend. Capture the Location header from the 302 response and redirect the user's browser to it.

Authentication: x-api-key is optional in production (recommended), required in staging.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key provided during onboarding. Optional in production (recommended for automatic agent allow-listing), required in staging.

Body

application/json

Same canonical application schema as the EnrollConnect API, with one additional deeplink-specific field: skip.

Build your payload once — the same JSON body works for both the deeplink and the EnrollConnect API (POST /api/v1/applications).

skipbooleanOptional

Deeplink only. When true, advances the user past any steps that are already complete based on the prefilled data. When false or omitted, the user starts at the first step.

Default: false

external_idstringOptional

Your unique identifier for this application.

_agent_idstringOptional

HealthSherpa-provided agent identifier (slug).

Example: your_agent_slug

tpa_slugstringOptional

HealthSherpa-assigned TPA identifier.

plan_hios_idstringRequired

14-character HIOS plan ID.

Example: 12345AB6780001

plan_yearintegerRequiredExample: 2026

desired_effective_datestring · dateOptionalExample: 2026-01-01

american_indian_or_alaskan_native_in_householdbooleanOptional

Responses

302

Redirect to HealthSherpa enrollment UI. The Location header contains the URL to redirect the user's browser to.

400

Malformed or missing required fields.

application/json

401

Missing or invalid API key (staging only).

application/json

422

Validation error (e.g., plan not found, invalid field values).

application/json

post

/public/ichra/v2/off_ex

HTTPcURLJavaScriptPython

POST /public/ichra/v2/off_ex HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 6182

{
  "skip": true,
  "external_id": "000001",
  "tpa_slug": "your_healthsherpa_provided_tpa_identifier",
  "_agent_id": "HS_SLUG",
  "plan_hios_id": "12345AB6780001",
  "plan_year": 2026,
  "desired_effective_date": "2026-01-01",
  "american_indian_or_alaskan_native_in_household": false,
  "agent_of_record": {
    "first_name": "James",
    "last_name": "Bond",
    "national_producer_number": "12342132",
    "carrier_producer_code": "CPC123",
    "state_license_number": "",
    "email": "[email protected]",
    "phone": "9172312312",
    "fax_number": "",
    "address": {
      "street_address_1": "123 Main St",
      "street_address_2": "",
      "city": "Austin",
      "state": "TX",
      "zip_code": "78701"
    },
    "signature": ""
  },
  "applicants": {
    "primary": {
      "first_name": "Jane",
      "middle_name": "",
      "last_name": "Doe",
      "suffix": "",
      "ssn": "",
      "itin": "",
      "date_of_birth": "1985-04-15",
      "gender": "female",
      "married": null,
      "us_citizen": true,
      "resides_in_state": true,
      "uses_tobacco": false,
      "tobacco_not_applicable": false,
      "race_ethnicity": "declined_to_answer",
      "hispanic_origin": "decline",
      "hispanic_origin_description": "",
      "language_spoken": "English",
      "language_written": "English",
      "external_id": "mem_001",
      "email": "[email protected]",
      "phone": "9172312312",
      "phone_type": "cell",
      "secondary_phone": "",
      "full_time_student": false,
      "graduation_date": null,
      "has_disability": false,
      "medicare_eligible": false,
      "enrolled_in_medicare": false,
      "enrolled_in_medicare_parts_a_or_b": false,
      "enrolled_in_medicaid_chip_or_other_gov_program": false,
      "veteran_or_active_duty_military": false,
      "currently_incarcerated": false,
      "has_eligible_immigration_status": null,
      "primary_requesting_coverage": true,
      "existing_coverage": {
        "has_existing_coverage": true,
        "plan_replaces_existing_coverage": true,
        "type": "issuer",
        "insurer": "ABC123",
        "policy_id": "ABC123",
        "policyholder_name": "Jane Doe",
        "start_date": "2025-01-01",
        "term_date": "2026-01-01",
        "will_continue": false
      },
      "guardian": {
        "first_name": "Jane",
        "middle_name": "",
        "last_name": "Doe",
        "suffix": "",
        "gender": "male",
        "relationship": "parent",
        "date_of_birth": "",
        "relationship_other": "",
        "email": "",
        "home_phone": "",
        "alternate_phone": "",
        "mailing_address": {
          "street_address_1": "456 Oak Ave",
          "street_address_2": "",
          "city": "Austin",
          "state": "TX",
          "zip_code": "78701",
          "fips_code": "48453"
        }
      },
      "responsible_party": {
        "first_name": "Susan",
        "middle_name": "",
        "last_name": "Doe",
        "date_of_birth": "1975-06-15",
        "sex": "female",
        "relationship": "parent_guardian",
        "phone": "5125559876",
        "street_address_1": "123 Main St",
        "street_address_2": "Apt 4B",
        "city": "Austin",
        "state": "TX",
        "zip_code": "78701"
      },
      "translator": {
        "first_name": "Maria",
        "middle_name": "",
        "last_name": "Garcia",
        "reason": "Primary applicant speaks Spanish"
      },
      "children_live_with_primary": true,
      "has_pediatric_dental_coverage": false,
      "previously_applied": false,
      "previously_applied_member_id": ""
    },
    "dependents": [
      {
        "first_name": "John",
        "middle_name": "",
        "last_name": "Doe",
        "suffix": "",
        "ssn": "",
        "itin": "",
        "date_of_birth": "1987-08-20",
        "gender": "male",
        "relationship": "spouse",
        "married": null,
        "us_citizen": true,
        "resides_in_state": true,
        "uses_tobacco": false,
        "tobacco_not_applicable": false,
        "race_ethnicity": "declined_to_answer",
        "hispanic_origin": "decline",
        "hispanic_origin_description": "",
        "language_spoken": "English",
        "language_written": "English",
        "email": "",
        "phone": "",
        "external_id": "mem_002",
        "full_time_student": false,
        "graduation_date": null,
        "has_disability": false,
        "medicare_eligible": false,
        "enrolled_in_medicare": false,
        "enrolled_in_medicare_parts_a_or_b": false,
        "enrolled_in_medicaid_chip_or_other_gov_program": false,
        "veteran_or_active_duty_military": false,
        "currently_incarcerated": false,
        "has_eligible_immigration_status": null,
        "existing_coverage": {
          "has_existing_coverage": false
        },
        "alternate_address": null,
        "guardian": null
      }
    ]
  },
  "residential_address": {
    "street_address_1": "123 Main St",
    "street_address_2": "",
    "city": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "fips_code": "48453"
  },
  "mailing_address": {
    "street_address_1": "123 Main St",
    "street_address_2": "",
    "city": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "fips_code": "48453",
    "different_from_home_address": false,
    "billing_use_only": false
  },
  "hra": {
    "offered_hra": true,
    "type": "ichra",
    "amount": 500,
    "contribution_covers": "premium",
    "used_for_spousal_or_family_premiums": "unknown",
    "start": "2025-09-01",
    "employer": {
      "name": "Acme Corporation",
      "external_id": "1234_abc",
      "phone": "5625551212",
      "fein": "123456789",
      "address": {
        "street_address_1": "123 Main St",
        "street_address_2": "",
        "city": "Austin",
        "state": "TX",
        "zip_code": "78701",
        "fips_code": "48453"
      }
    },
    "premium_payer": "employer",
    "household_size": 3,
    "annual_household_income": 75000,
    "annual_household_income_determination": "self-reported"
  },
  "special_enrollment_period": {
    "event_type": "offered_ichra",
    "event_date": "2026-01-01"
  },
  "attestations": {
    "agrees_issuer_attestations": true,
    "broker_signature_attestation": false,
    "electronic_signature_consent": true,
    "disclosure_statement_accepted": false,
    "coverage_replacement_attestation_accepted": false,
    "pediatric_dental": "purchased_separately",
    "agent_submitted_application": true,
    "agent_provided_consumer_marketing_materials": false,
    "agent_advised_consumer_of_product_features": true,
    "agent_retained_signed_application_copy": true,
    "consumer_working_with_agent": true,
    "spouse_or_dependent_authorization": true
  },
  "signatures": {
    "signature_date": "2026-01-02",
    "pediatric_dental_signature": "",
    "pediatric_dental_signature_date": null,
    "translator_signature_date": null,
    "state_supplement_primary_signature": "",
    "state_supplement_spouse_signature": "",
    "state_supplement_disclosures_signature": ""
  },
  "communication_preferences": {
    "application_notification_email": true,
    "application_notification_call": false,
    "application_notification_text": false,
    "email_contact_consent": true,
    "marketing_contact_consent": false,
    "decline_marketing_contact": false,
    "preferred_communication_method": "email",
    "agrees_hsa_contact_opt_in": false,
    "communication_preference_affirmed": true
  },
  "analytics": {
    "utm_source": "",
    "utm_medium": "",
    "utm_campaign": "",
    "utm_term": "",
    "utm_content": ""
  },
  "payment_method": {
    "payment_method_type": "bank_account",
    "first_name": "John",
    "last_name": "Doe",
    "address": {
      "street_address_1": "123 Main St",
      "street_address_2": "",
      "city": "Austin",
      "state": "TX",
      "zip_code": "78701"
    },
    "eft_routing": "123456789",
    "eft_number": "1234567890",
    "eft_type": "checking",
    "eft_level": "personal",
    "bank_name": "Bank of America",
    "payment_type": "both",
    "authorization_timestamp": "2026-01-14T15:34:00Z"
  }
}

No content