Application Deeplink API

The Application Deeplink allows for platforms to enroll ICHRA participants through their HealthSherpa application.

The Application Deeplink API in Production is not strictly required, but recommended. One benefit of passing an API Key is that we automatically whitelist any valid _agent_id passed in your request.

In Staging, Basic Auth is required for it to work. Please reach out to your on-boarding representative for the Staging basic authentication credentials.

Environments:

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

Successful POST behavior:

When the Deeplink API request succeeds, the response includes a URL you should immediately route the user’s browser to. This navigation can occur in the current tab or in a new tab/window (e.g. using target="_blank"). The browser will handle all subsequent redirects automatically, and the user will land on the pre-filled application. Keep in mind that the more fields you pre-populate, the longer the final page may take to render.

Note on Postman testing: This flow uses browser-style redirects and session cookies. While Postman will follow redirects and show the final response, it does not execute JavaScript or render pages like a browser. The final HTML may differ from what you see when opening the same URL in a browser, since Postman does not carry the full browser context. Use a real browser (or a headless browser tool such as Playwright) if you need to verify the complete end-user experience.

Apply for ICHRA off-exchange coverage via deeplink

post

Public endpoint for initiating an ICHRA off-exchange application with prefilled fields. Prefill behavior is controlled via request body. Requires plan_hios_id, _agent_id, zip_code, fip_code, and either phone_number or email.

Note: If any applicants other than primary are included (e.g., spouse, domestic_partner, dependents), then the primary applicant is required.

Authentication:

• Production: You may optionally send an x-api-key header. Providing a valid API key will automatically allowlist any valid _agent_id included in your request, allowing agents not associated with an agency to proceed. _agent_id remains required in all cases.

• Staging: Basic Auth is required. Please contact your onboarding representative for credentials.

Header parameters

x-api-keystringOptional

Optional API key used in Production. When provided and valid, it allows use of a valid _agent_id that is not associated with an agency. _agent_id is still required. In Staging, this header is not used; Basic Auth is required instead.

Body

application/json

plan_hios_idstringRequired

HIOS ID of the selected plan

Example: 53901AZ1420167

_agent_idstringRequired

Slug of the agent of record

Example: your_healthsherpa_provided_agent_identifier

agent_of_record_cpcstringOptional

Carrier Producer Code of the agent of record

Example: CPC123456

agent_of_record_tinstringOptional

Tax Identification Number of the agent of record or agency, if preferred.

Example: 123456789

agent_of_record_email_addressstring · emailOptional

Email address of the agent of record. If not provided, the email address associated with the _agent_id will be used.

Example: [email protected]

agent_of_record_first_namestringOptional

First name of the agent of record. If not provided, the first name associated with the _agent_id will be used.

Example: John

agent_of_record_last_namestringOptional

Last name of the agent of record. If not provided, the last name associated with the _agent_id will be used.

Example: Doe

agent_of_record_npnstringOptional

NPN of the agent of record. Must be 1-10 digits and not start with 0. If not provided, the NPN associated with the _agent_id will be used.

Example: 1234567890

agent_of_record_phone_numberstringOptional

Phone number of the agent of record. Must be 10 digits and cannot start with 0, 1, or 9. Can be all digits (5625551212) or with dashes (562-555-1212).

Example: 5625551212

agent_of_record_state_licensestringOptional

State license of the agent of record. This will not be taken from the _agent_id.

Example: 1234567890

emailstring · emailOptional

Email for the application (required if phone_number is not provided)

Example: [email protected]

phone_numberstringOptional

Phone number for the application (required if email is not provided)

Example: 5625554567

phone_typestring · enumOptional

Type of phone number provided

Example: cellPossible values:

external_idstringOptional

External identifier for the application

Example: your_member_identifier

utm_sourcestringOptional

UTM source parameter for tracking

utm_mediumstringOptional

UTM medium parameter for tracking

utm_campaignstringOptional

UTM campaign parameter for tracking

utm_termstringOptional

UTM term parameter for tracking

utm_contentstringOptional

UTM content parameter for tracking

ljsstringOptional

LJS parameter

callstringOptional

Call parameter

plan_yearintegerOptional

Plan year (defaults to current year if not provided)

street_addressstringOptional

Street address

Example: 333 Main Dr

street_address_unit_numberstringOptional

Street address unit number

Example: Q

citystringOptional

City

Example: Springfield

statestring · enumOptional

State

Example: AZPossible values:

zip_codestringRequired

ZIP code (must be exactly 5 digits)

Example: 85040

fip_codestringRequired

County code (FIPS) (must be exactly 5 digits)

Example: 04013

mailing_street_addressstringOptional

Mailing street address (if different from residential)

Example: 444 Main Dr

mailing_citystringOptional

Mailing city (if different from residential)

Example: Washington

mailing_statestring · enumOptional

Mailing state (if different from residential)

Example: AZPossible values:

mailing_zip_codestringOptional

Mailing ZIP code (if different from residential)

Example: 85040

mailing_fip_codestringOptional

Mailing county code (FIPS) (if different from residential)

Example: 04013

sep_reasonstring · enumOptional

Special enrollment period reason

Example: offered_ichraPossible values:

sep_reason_datestring · dateOptional

Special enrollment period reason date

Example: 2025-09-01

language_spokenstring · enumOptional

The preferred spoken language of the applicant.

Possible values:

language_writtenstring · enumOptional

The preferred written language of the applicant.

Possible values:

skipbooleanOptional

Whether to skip to the latest possible step in the application

Example: true

pediatricstring · enumOptional

Pediatric dental coverage status

Example: not_applicablePossible values:

Responses

302

Success - Redirects to application/enrollment page

401

Error - Authentication required (staging environment)

406

Error - Access blocked from outside United States

422

Error - Plan not available for off-ex marketplace, missing required parameters, or malformed input

429

Error - Rate limit exceeded

500

Error - Internal server error

post

/public/ichra/off_ex

HTTPcURLJavaScriptPython

POST /public/ichra/off_ex HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2904

{
  "plan_hios_id": "53901AZ1420167",
  "_agent_id": "your_healthsherpa_provided_agent_identifier",
  "agent_of_record_cpc": "CPC123456",
  "agent_of_record_tin": "123456789",
  "agent_of_record_email_address": "[email protected]",
  "agent_of_record_first_name": "John",
  "agent_of_record_last_name": "Doe",
  "agent_of_record_npn": "1234567890",
  "agent_of_record_phone_number": "5625551212",
  "agent_of_record_state_license": "1234567890",
  "email": "[email protected]",
  "phone_number": "5625554567",
  "phone_type": "cell",
  "external_id": "your_member_identifier",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "ichra_2025",
  "utm_term": "health_insurance",
  "utm_content": "banner_ad",
  "ljs": "true",
  "call": "enrollment",
  "plan_year": 2026,
  "street_address": "333 Main Dr",
  "street_address_unit_number": "Q",
  "city": "Springfield",
  "state": "AZ",
  "zip_code": "85040",
  "fip_code": "04013",
  "mailing_street_address": "444 Main Dr",
  "mailing_city": "Washington",
  "mailing_state": "AZ",
  "mailing_zip_code": "85040",
  "mailing_fip_code": "04013",
  "sep_reason": "offered_ichra",
  "sep_reason_date": "2025-09-01",
  "language_spoken": "english",
  "language_written": "english",
  "skip": true,
  "pediatric": "not_applicable",
  "applicants": {
    "primary": {
      "first_name": "Emily",
      "middle_name": "Jane",
      "last_name": "Davis",
      "suffix": "Sr.",
      "gender": "female",
      "date_of_birth": "1990-03-04",
      "us_citizen": true,
      "resides_in_state": true,
      "uses_tobacco": "false",
      "race_ethnicity": "decline_to_answer",
      "hispanic_origin": "decline_to_answer",
      "ssn": "717052794",
      "has_existing_coverage": false,
      "hra": {
        "type": "ichra",
        "amount": 500,
        "contribution_covers": "premium",
        "start": "2025-09-01",
        "name": "Acme Corporation",
        "phone": "5625551212",
        "street_address": "123 Employer St",
        "city": "Phoenix",
        "state": "AZ",
        "zip_code": "85001",
        "fein": "123456789",
        "premium_payer": "employer",
        "household_size": 3,
        "annual_household_income": 75000,
        "annual_household_income_determination": "self-reported",
        "offered_hra": true,
        "offered_hra_unknown": false,
        "tpa_slug": "your_healthsherpa_provided_tpa_identifier"
      }
    },
    "spouse": {
      "first_name": "Michael",
      "middle_name": "J",
      "last_name": "Doe",
      "suffix": "Jr.",
      "gender": "male",
      "date_of_birth": "1988-07-15",
      "us_citizen": true,
      "resides_in_state": true,
      "uses_tobacco": "false",
      "race_ethnicity": "decline_to_answer",
      "hispanic_origin": "decline_to_answer",
      "ssn": "717052795",
      "has_existing_coverage": false
    },
    "dependents": [
      {
        "first_name": "Noah",
        "middle_name": "James",
        "last_name": "Davis",
        "suffix": "Jr.",
        "gender": "male",
        "date_of_birth": "2021-12-01",
        "us_citizen": true,
        "resides_in_state": false,
        "uses_tobacco": false,
        "race_ethnicity": "decline_to_answer",
        "hispanic_origin": "decline_to_answer",
        "ssn": "717052796",
        "has_existing_coverage": false
      },
      {
        "first_name": "Minerva",
        "middle_name": "Rose",
        "last_name": "Davis",
        "suffix": "II",
        "gender": "female",
        "date_of_birth": "2018-10-01",
        "us_citizen": true,
        "resides_in_state": false,
        "uses_tobacco": false,
        "race_ethnicity": "decline_to_answer",
        "hispanic_origin": "decline_to_answer",
        "ssn": "717052797",
        "has_existing_coverage": false
      }
    ]
  }
}

No content