EnrollConnect API Specification

Overview

The EnrollConnect API provides full lifecycle control over off-exchange enrollment applications, from creation through carrier submission, status tracking, and post-submission actions (cancel, terminate).

For implementation details, worked examples, and step-by-step integration instructions, see the EnrollConnect Guide.

The request schema below is the canonical application schema shared with the Deeplinks V2 API. Build your payload once and route it to either endpoint based on the Enrollment Decision Path.

Base URLs

Environment

Base URL

Staging

https://api.ichra-staging.healthsherpa.com

Production

https://api.ichra.healthsherpa.com

Authentication uses the x-api-key header for all endpoints.

Rate Limits

Scope

Limit

Per authenticated API key

50 requests per minute

Exceeding the limit returns 429 Too Many Requests with a retry_after value (in seconds) in the JSON response body.

Error Format

All error responses, whether from validation, authentication, or system errors, return a consistent structure:

{
  "errors": [
    {
      "code": "missing_required_field",
      "field": "applicants.primary.ssn",
      "message": "Primary applicant SSN is required for submission"
    }
  ]
}

Each entry in the errors array contains:

Property

Required

Description

code

Yes

Machine-readable enum. Switch on this value rather than parsing message strings.

message

Yes

Human-readable description. May change over time; do not rely on exact wording.

field

Dot-path to the offending request field. Present only for field-level validation errors.

The errors array returned on every POST, PUT, and GET response uses the same structure. When this array is empty, the application is ready to submit.

See the EnrollConnect Guide for the full list of error codes and recommended handling patterns.

Hypermedia Actions (`next_actions`)

Every application response includes a next_actions array containing the available operations for the application in its current state. Each entry provides the relation type, URL, and HTTP method so your platform can drive the workflow without hardcoding URLs.

"next_actions": [
  {"rel": "self", "href": "/api/v1/applications/HSA000000001", "method": "GET"},
  {"rel": "update", "href": "/api/v1/applications/HSA000000001", "method": "PUT"},
  {"rel": "validate", "href": "/api/v1/applications/HSA000000001/validate", "method": "GET"},
  {"rel": "submit", "href": "/api/v1/applications/HSA000000001/submit", "method": "POST"},
  {"rel": "upload_supporting_documentation", "href": "/api/v1/applications/HSA000000001/supporting_documentation", "method": "POST"},
  {"rel": "payment_redirect", "href": "/api/v1/applications/HSA000000001/payment_redirect", "method": "GET"}
]

Property

Required

Description

rel

Yes

Relation type: self, update, validate, submit, cancel, terminate, payment_redirect, upload_supporting_documentation

href

Yes

Relative URL for the action

method

Yes

HTTP verb (GET, PUT, POST)

required

When true, this action is a submission prerequisite that must be completed before submit will succeed

The array is state-aware — it changes based on policy_status and carrier capabilities:

Application state

Available actions

draft (pre-submission)

self, update, validate, submit, upload_supporting_documentation, payment_redirect (if carrier supports it)

pending_effectuation

self, cancel, payment_redirect (if carrier supports it)

effectuated

self, cancel, terminate

cancelled / terminated

self

Submission readiness

Use errors and next_actions together to determine if an application is ready to submit:

errors is empty → the application data is valid (all field-level issues resolved)
No next_actions entries have required: true → all prerequisite steps are done (documentation uploaded, payment completed, etc.)
Both conditions met → the application can be submitted

This keeps the distinction clean: errors is for data issues fixable via PUT, while required actions are steps that need separate API calls.

Use rel values to determine what to show in your UI rather than hardcoding endpoint paths.

Future Functionality

The initial release covers the core application lifecycle: create, update, submit, retrieve, cancel, and terminate. The following endpoints are planned as fast-follow additions:

Functionality

Description

PUT /api/v1/applications/:id/payment_method

Set or update payment method independently of a full application update. Required for carriers like Cigna and Elevance that require payment before or with submission

GET /api/v1/applications

Paginated list with filters (status, plan, updated_since) for bulk status polling

PATCH /api/v1/applications/:id

Partial update support. To start, PUT will require the complete payload.

Enrollment requirements on plan lookup

GET /plans/:hios_id?plan_year= will include an enrollment_requirements object with required fields, conditionally required fields, and payment/SEP metadata per carrier.

These endpoints are included in the spec below as a preview. Schemas and behavior are subject to change.

Payment and PCI Compliance

Payment information is managed exclusively through PUT /api/v1/applications/:id/payment_method, not through the application create or update endpoints. This separation ensures a clean PCI boundary.

Sensitive payment fields (credit card number, CVV, bank account and routing numbers) must be sent through a PCI-compliant proxy rather than directly to the API. HealthSherpa will provide a proxy route URL per environment. Your platform sends payment data to this URL; the proxy tokenizes sensitive fields in transit before they reach HealthSherpa. This keeps both your platform and HealthSherpa out of PCI scope.

The GET /api/v1/applications/:id response includes a payment object with carrier-reported payment data (status, paid-through date, balance due, autopay indicator) when available. For carriers that use payment redirect, this data depends on the carrier reporting it back. Sensitive payment method values are never returned in any API response.

Details on the proxy URL, supported fields, and integration steps will be provided when these capabilities are available.

API Specification

Create application

post

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

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Body

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_idstringOptional

Your unique identifier for this application.

Example: partner_app_001

_agent_idstringOptional

HealthSherpa-provided agent identifier (slug). Required for deeplink; optional for API if using TPA auth.

Example: your_agent_slug

tpa_slugstringOptional

HealthSherpa-assigned TPA identifier (provided during onboarding).

Example: your_tpa_slug

plan_hios_idstringRequired

14-character HIOS plan ID.

Example: 12345AB6780001

plan_yearintegerRequiredExample: 2026

desired_effective_datestring · dateOptional

Requested effective date. Actual date determined by SEP/OEP rules.

Example: 2026-01-01

american_indian_or_alaskan_native_in_householdbooleanOptional

Responses

201

Application created

application/json

400

Malformed or missing required fields.

application/json

401

Missing or invalid API key.

application/json

422

Syntactically valid but semantically incorrect.

application/json

post

/api/v1/applications

POST /api/v1/applications HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 5763

{
  "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": ""
  }
}

{
  "application_id": "HSA000000001",
  "external_id": "000001",
  "tpa_slug": "your_tpa_slug",
  "policy_status": "draft",
  "document_status": "none_needed",
  "sep_reason": "offered_ichra",
  "created_at": "2026-01-14T15:34:00Z",
  "updated_at": "2026-01-14T15:34:00Z",
  "submitted_at": null,
  "desired_effective_date": "2026-02-01",
  "plan_hios_id": "12345AB6780001",
  "plan_year": 2026,
  "issuer_hios_id": "12345",
  "payment_instructions": {
    "payment_required_with_submission": false,
    "payment_redirect_supported": true,
    "pay_by_phone_supported": false,
    "payment_phone_number": "8005551212"
  },
  "payment": {
    "payment_status": "paid",
    "payment_status_updated_date": "2026-06-15",
    "grace_period_start_date": "2026-06-10",
    "paid_through_date": "2026-07-31",
    "past_due_member_responsibility_balance_due": "0.00",
    "current_member_responsibility_balance_due": "50.50",
    "autopay_indicator": true
  },
  "policies": [
    {
      "policy_id": "HSP000000001",
      "effective_date": "2026-02-01",
      "expiration_date": "2026-12-31",
      "status": "pending_effectuation",
      "plan_hios_id": "12345AB6780001",
      "gross_premium": 750.25,
      "members": [
        {
          "member_id": "text",
          "effective_date": "2026-03-10",
          "removed_date": "2026-03-10"
        }
      ],
      "agent_of_record": {
        "npn": "12342132",
        "first_name": "James",
        "last_name": "Bond",
        "state_license_number": "TX-123456",
        "email": "[email protected]"
      },
      "payment": {
        "payment_status": "paid",
        "payment_status_updated_date": "2026-06-15",
        "grace_period_start_date": "2026-06-10",
        "paid_through_date": "2026-07-31",
        "past_due_member_responsibility_balance_due": "0.00",
        "current_member_responsibility_balance_due": "50.50",
        "autopay_indicator": true
      }
    }
  ],
  "application": {},
  "errors": [
    {
      "code": "missing_required_field",
      "field": "applicants.primary.ssn",
      "message": "Primary applicant SSN is required for submission"
    },
    {
      "code": "invalid_field_value",
      "field": "applicants.primary.race_ethnicity",
      "message": "race_ethnicity must be a valid option"
    }
  ],
  "next_actions": [
    {
      "rel": "validate",
      "href": "/api/v1/applications/HSA000000001/validate",
      "method": "GET"
    },
    {
      "rel": "submit",
      "href": "/api/v1/applications/HSA000000001/submit",
      "method": "POST"
    },
    {
      "rel": "upload_supporting_documentation",
      "href": "/api/v1/applications/HSA000000001/supporting_documentation",
      "method": "POST"
    }
  ]
}

Update application

put

Full replacement of application state. Partial updates are not supported. Applications can only be updated before submission.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Path parameters

idstringRequired

HealthSherpa application ID.

Example: HSA000000001

Body

external_idstringOptional

Your unique identifier for this application.

Example: partner_app_001

_agent_idstringOptional

HealthSherpa-provided agent identifier (slug). Required for deeplink; optional for API if using TPA auth.

Example: your_agent_slug

tpa_slugstringOptional

HealthSherpa-assigned TPA identifier (provided during onboarding).

Example: your_tpa_slug

plan_hios_idstringRequired

14-character HIOS plan ID.

Example: 12345AB6780001

plan_yearintegerRequiredExample: 2026

desired_effective_datestring · dateOptional

Requested effective date. Actual date determined by SEP/OEP rules.

Example: 2026-01-01

american_indian_or_alaskan_native_in_householdbooleanOptional

Responses

200

Application updated

application/json

application_idstringOptionalExample: HSA000000001

external_idstringOptionalExample: 000001

tpa_slugstringOptionalExample: your_tpa_slug

policy_statusstring · enumOptional

draft when the application has not yet been submitted. Transitions to pending_effectuation on successful submission.

Example: draftPossible values:

document_statusstring · enum · nullableOptional

SEP document verification status. none_needed: no documentation required. required: documentation required but not yet uploaded. uploaded: documentation uploaded, pending verification. verified: documentation verified. denied: documentation denied.

Example: none_neededPossible values:

sep_reasonstring · nullableOptionalExample: offered_ichra

created_atstring · date-timeOptionalExample: 2026-01-14T15:34:00Z

updated_atstring · date-timeOptionalExample: 2026-01-14T15:34:00Z

submitted_atstring · date-time · nullableOptional

desired_effective_datestring · dateOptionalExample: 2026-02-01

plan_hios_idstringOptionalExample: 12345AB6780001

plan_yearintegerOptionalExample: 2026

issuer_hios_idstringOptionalExample: 12345

applicationobjectOptional

Echo of the application data as stored.

400

Malformed or missing required fields.

application/json

401

Missing or invalid API key.

application/json

404

Application not found.

application/json

409

Application already pending or effectuated.

422

Syntactically valid but semantically incorrect.

application/json

put

/api/v1/applications/{id}

PUT /api/v1/applications/{id} HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 6615

{
  "external_id": "partner_app_001",
  "_agent_id": "your_agent_slug",
  "tpa_slug": "your_tpa_slug",
  "plan_hios_id": "12345AB6780001",
  "plan_year": 2026,
  "desired_effective_date": "2026-01-01",
  "agent_of_record": {
    "first_name": "James",
    "last_name": "Bond",
    "national_producer_number": "12342132",
    "carrier_producer_code": "ABCDEFGHYZ",
    "state_license_number": "TX-123456",
    "email": "[email protected]",
    "phone": "9172312312",
    "fax_number": "9172312313",
    "address": {
      "street_address_1": "123 Main St",
      "street_address_2": "",
      "city": "Austin",
      "state": "TX",
      "zip_code": "78701"
    },
    "signature": "text"
  },
  "applicants": {
    "primary": {
      "first_name": "Jane",
      "middle_name": "Marie",
      "last_name": "Doe",
      "suffix": "",
      "ssn": "123456789",
      "itin": "",
      "date_of_birth": "1985-04-15",
      "gender": "male",
      "married": false,
      "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,
      "existing_coverage": {
        "has_existing_coverage": true,
        "plan_replaces_existing_coverage": true,
        "type": "issuer",
        "insurer": "Aetna",
        "policy_id": "POL-987654",
        "policyholder_name": "Jane Doe",
        "start_date": "2025-01-01",
        "term_date": "2026-01-01",
        "will_continue": false
      },
      "guardian": {
        "first_name": "Robert",
        "middle_name": "",
        "last_name": "Doe",
        "suffix": "",
        "gender": "male",
        "relationship": "parent",
        "date_of_birth": "1960-03-10",
        "relationship_other": "",
        "email": "[email protected]",
        "home_phone": "5125551234",
        "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": "",
      "primary_requesting_coverage": true
    },
    "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": true,
          "plan_replaces_existing_coverage": true,
          "type": "issuer",
          "insurer": "Aetna",
          "policy_id": "POL-987654",
          "policyholder_name": "Jane Doe",
          "start_date": "2025-01-01",
          "term_date": "2026-01-01",
          "will_continue": false
        },
        "alternate_address": {
          "street_address_1": "456 Oak Ave",
          "street_address_2": "Apt 2B",
          "city": "Dallas",
          "state": "TX",
          "zip_code": "75201",
          "fips_code": "48113",
          "reason": "Attending college"
        },
        "guardian": {
          "first_name": "Robert",
          "middle_name": "",
          "last_name": "Doe",
          "suffix": "",
          "gender": "male",
          "relationship": "parent",
          "date_of_birth": "1960-03-10",
          "relationship_other": "",
          "email": "[email protected]",
          "home_phone": "5125551234",
          "alternate_phone": "",
          "mailing_address": {
            "street_address_1": "456 Oak Ave",
            "street_address_2": "",
            "city": "Austin",
            "state": "TX",
            "zip_code": "78701",
            "fips_code": "48453"
          }
        }
      }
    ]
  },
  "residential_address": {
    "street_address_1": "123 Main St",
    "street_address_2": "text",
    "city": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "fips_code": "48453"
  },
  "mailing_address": {
    "street_address_1": "123 Main St",
    "street_address_2": "text",
    "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": "true",
    "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": "text",
        "city": "Austin",
        "state": "TX",
        "zip_code": "78701",
        "fips_code": "48453"
      }
    },
    "premium_payer": "text",
    "household_size": 3,
    "annual_household_income": 75000,
    "annual_household_income_determination": "text"
  },
  "special_enrollment_period": {
    "event_type": "offered_ichra",
    "event_date": "2026-01-01"
  },
  "attestations": {
    "agrees_issuer_attestations": true,
    "broker_signature_attestation": true,
    "electronic_signature_consent": true,
    "disclosure_statement_accepted": true,
    "coverage_replacement_attestation_accepted": true,
    "pediatric_dental": "purchased_separately",
    "agent_submitted_application": true,
    "agent_provided_consumer_marketing_materials": true,
    "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-03-10",
    "pediatric_dental_signature": "text",
    "pediatric_dental_signature_date": "2026-03-10",
    "translator_signature_date": "2026-03-10",
    "state_supplement_primary_signature": "text",
    "state_supplement_spouse_signature": "text",
    "state_supplement_disclosures_signature": "text"
  },
  "communication_preferences": {
    "application_notification_email": true,
    "application_notification_call": true,
    "application_notification_text": true,
    "email_contact_consent": true,
    "marketing_contact_consent": true,
    "decline_marketing_contact": true,
    "preferred_communication_method": "email",
    "agrees_hsa_contact_opt_in": true,
    "communication_preference_affirmed": true
  },
  "american_indian_or_alaskan_native_in_household": true,
  "analytics": {
    "utm_source": "text",
    "utm_medium": "text",
    "utm_campaign": "text",
    "utm_term": "text",
    "utm_content": "text"
  }
}

{
  "application_id": "HSA000000001",
  "external_id": "000001",
  "tpa_slug": "your_tpa_slug",
  "policy_status": "draft",
  "document_status": "none_needed",
  "sep_reason": "offered_ichra",
  "created_at": "2026-01-14T15:34:00Z",
  "updated_at": "2026-01-14T15:34:00Z",
  "submitted_at": null,
  "desired_effective_date": "2026-02-01",
  "plan_hios_id": "12345AB6780001",
  "plan_year": 2026,
  "issuer_hios_id": "12345",
  "payment_instructions": {
    "payment_required_with_submission": false,
    "payment_redirect_supported": true,
    "pay_by_phone_supported": false,
    "payment_phone_number": "8005551212"
  },
  "payment": {
    "payment_status": "paid",
    "payment_status_updated_date": "2026-06-15",
    "grace_period_start_date": "2026-06-10",
    "paid_through_date": "2026-07-31",
    "past_due_member_responsibility_balance_due": "0.00",
    "current_member_responsibility_balance_due": "50.50",
    "autopay_indicator": true
  },
  "policies": [
    {
      "policy_id": "HSP000000001",
      "effective_date": "2026-02-01",
      "expiration_date": "2026-12-31",
      "status": "pending_effectuation",
      "plan_hios_id": "12345AB6780001",
      "gross_premium": 750.25,
      "members": [
        {
          "member_id": "text",
          "effective_date": "2026-03-10",
          "removed_date": "2026-03-10"
        }
      ],
      "agent_of_record": {
        "npn": "12342132",
        "first_name": "James",
        "last_name": "Bond",
        "state_license_number": "TX-123456",
        "email": "[email protected]"
      },
      "payment": {
        "payment_status": "paid",
        "payment_status_updated_date": "2026-06-15",
        "grace_period_start_date": "2026-06-10",
        "paid_through_date": "2026-07-31",
        "past_due_member_responsibility_balance_due": "0.00",
        "current_member_responsibility_balance_due": "50.50",
        "autopay_indicator": true
      }
    }
  ],
  "application": {},
  "errors": [
    {
      "code": "missing_required_field",
      "field": "applicants.primary.ssn",
      "message": "Primary applicant SSN is required for submission"
    },
    {
      "code": "invalid_field_value",
      "field": "applicants.primary.race_ethnicity",
      "message": "race_ethnicity must be a valid option"
    }
  ],
  "next_actions": [
    {
      "rel": "validate",
      "href": "/api/v1/applications/HSA000000001/validate",
      "method": "GET"
    },
    {
      "rel": "submit",
      "href": "/api/v1/applications/HSA000000001/submit",
      "method": "POST"
    },
    {
      "rel": "upload_supporting_documentation",
      "href": "/api/v1/applications/HSA000000001/supporting_documentation",
      "method": "POST"
    }
  ]
}

Get application

get

Full application record including policy status, payment instructions, and carrier data.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Path parameters

idstringRequired

HealthSherpa application ID.

Example: HSA000000001

Responses

200

Application details

application/json

application_idstringOptionalExample: HSA000000001

external_idstringOptionalExample: 000001

tpa_slugstringOptionalExample: your_tpa_slug

policy_statusstring · enumOptional

draft when the application has not yet been submitted. Transitions to pending_effectuation on successful submission.

Example: draftPossible values:

document_statusstring · enum · nullableOptional

Example: none_neededPossible values:

sep_reasonstring · nullableOptionalExample: offered_ichra

created_atstring · date-timeOptionalExample: 2026-01-14T15:34:00Z

updated_atstring · date-timeOptionalExample: 2026-01-14T15:34:00Z

submitted_atstring · date-time · nullableOptional

desired_effective_datestring · dateOptionalExample: 2026-02-01

plan_hios_idstringOptionalExample: 12345AB6780001

plan_yearintegerOptionalExample: 2026

issuer_hios_idstringOptionalExample: 12345

applicationobjectOptional

Echo of the application data as stored.

401

Missing or invalid API key.

application/json

404

Application not found.

application/json

get

/api/v1/applications/{id}

GET /api/v1/applications/{id} HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "application_id": "HSA000000001",
  "external_id": "000001",
  "tpa_slug": "your_tpa_slug",
  "policy_status": "draft",
  "document_status": "none_needed",
  "sep_reason": "offered_ichra",
  "created_at": "2026-01-14T15:34:00Z",
  "updated_at": "2026-01-14T15:34:00Z",
  "submitted_at": null,
  "desired_effective_date": "2026-02-01",
  "plan_hios_id": "12345AB6780001",
  "plan_year": 2026,
  "issuer_hios_id": "12345",
  "payment_instructions": {
    "payment_required_with_submission": false,
    "payment_redirect_supported": true,
    "pay_by_phone_supported": false,
    "payment_phone_number": "8005551212"
  },
  "payment": {
    "payment_status": "paid",
    "payment_status_updated_date": "2026-06-15",
    "grace_period_start_date": "2026-06-10",
    "paid_through_date": "2026-07-31",
    "past_due_member_responsibility_balance_due": "0.00",
    "current_member_responsibility_balance_due": "50.50",
    "autopay_indicator": true
  },
  "policies": [
    {
      "policy_id": "HSP000000001",
      "effective_date": "2026-02-01",
      "expiration_date": "2026-12-31",
      "status": "pending_effectuation",
      "plan_hios_id": "12345AB6780001",
      "gross_premium": 750.25,
      "members": [
        {
          "member_id": "text",
          "effective_date": "2026-03-10",
          "removed_date": "2026-03-10"
        }
      ],
      "agent_of_record": {
        "npn": "12342132",
        "first_name": "James",
        "last_name": "Bond",
        "state_license_number": "TX-123456",
        "email": "[email protected]"
      },
      "payment": {
        "payment_status": "paid",
        "payment_status_updated_date": "2026-06-15",
        "grace_period_start_date": "2026-06-10",
        "paid_through_date": "2026-07-31",
        "past_due_member_responsibility_balance_due": "0.00",
        "current_member_responsibility_balance_due": "50.50",
        "autopay_indicator": true
      }
    }
  ],
  "application": {},
  "errors": [
    {
      "code": "missing_required_field",
      "field": "applicants.primary.ssn",
      "message": "Primary applicant SSN is required for submission"
    },
    {
      "code": "invalid_field_value",
      "field": "applicants.primary.race_ethnicity",
      "message": "race_ethnicity must be a valid option"
    }
  ],
  "next_actions": [
    {
      "rel": "validate",
      "href": "/api/v1/applications/HSA000000001/validate",
      "method": "GET"
    },
    {
      "rel": "submit",
      "href": "/api/v1/applications/HSA000000001/submit",
      "method": "POST"
    },
    {
      "rel": "upload_supporting_documentation",
      "href": "/api/v1/applications/HSA000000001/supporting_documentation",
      "method": "POST"
    }
  ]
}

List applications (stretch for launch)

get

Paginated list of applications. Supports filtering by status, plan, and timestamps. This endpoint is a stretch goal for the initial launch and may be available shortly after.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Query parameters

policy_statusstring · enumOptionalPossible values:

external_idstringOptional

plan_yearintegerOptionalExample: 2026

issuer_hios_idstringOptionalExample: 12345

plan_hios_idstringOptionalExample: 12345AB6780001

employer_external_idstringOptional

Filter by the employer's external identifier.

updated_sincestring · date-timeOptional

ISO 8601. Returns applications updated after this time.

limitinteger · max: 100OptionalDefault: 25

offsetintegerOptionalDefault: 0

Responses

200

List of applications

application/json

401

Missing or invalid API key.

application/json

get

/api/v1/applications

GET /api/v1/applications HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "applications": [
    {
      "application_id": "HSA000000000",
      "external_id": "000001",
      "employer_external_id": "abc",
      "plan_year": "2026",
      "plan_hios_id": "12345AB12345212",
      "exchange_type": "off_exchange",
      "policy_status": "effectuated",
      "created_at": "2025-06-15T14:22:01Z",
      "updated_at": "2025-07-01T10:05:12Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 214
  }
}

Upload supporting documentation

post

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.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Path parameters

idstringRequired

HealthSherpa application ID.

Example: HSA000000001

Body

filestring · binaryRequired

The document file (PDF, JPEG, or PNG).

document_typestringOptional

Type of supporting document being uploaded.

Example: sep_verification

Responses

201

Document uploaded

application/json

401

Missing or invalid API key.

application/json

404

Application not found.

application/json

422

Syntactically valid but semantically incorrect.

application/json

post

/api/v1/applications/{id}/supporting_documentation

POST /api/v1/applications/{id}/supporting_documentation HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 52

{
  "file": "binary",
  "document_type": "sep_verification"
}

{
  "document_id": "DOC000000001",
  "application_id": "HSA000000001",
  "filename": "ichra_offering.pdf",
  "document_type": "sep_verification",
  "uploaded_at": "2026-01-14T16:05:00Z"
}

Submit application

post

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.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Path parameters

idstringRequired

HealthSherpa application ID.

Example: HSA000000001

Responses

200

Application submitted, now pending effectuation

application/json

application_idstringOptionalExample: HSA000000001

external_idstringOptionalExample: 000001

plan_yearintegerOptionalExample: 2026

plan_hios_idstringOptionalExample: 12345AB6780001

policy_statusstringOptionalExample: pending_effectuation

submitted_atstring · date-timeOptionalExample: 2026-01-14T16:00:00Z

401

Missing or invalid API key.

application/json

404

Application not found.

application/json

422

Not submittable or fails validation.

application/json

post

/api/v1/applications/{id}/submit

POST /api/v1/applications/{id}/submit HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "application_id": "HSA000000001",
  "external_id": "000001",
  "plan_year": 2026,
  "plan_hios_id": "12345AB6780001",
  "policy_status": "pending_effectuation",
  "payment_instructions": {
    "payment_required_with_submission": false,
    "payment_redirect_supported": true,
    "pay_by_phone_supported": false,
    "payment_phone_number": "8005551212"
  },
  "submitted_at": "2026-01-14T16:00:00Z"
}

Get payment redirect data

get

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.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Path parameters

idstringRequired

HealthSherpa application ID.

Example: HSA000000001

Responses

200

Payment redirect data returned

application/json

application_idstringOptionalExample: HSA000000001

methodstring · enumOptional

HTTP method to use. Always POST.

Example: POSTPossible values:

endpointstring · uriOptional

The carrier's payment URL. Submit the form POST to this URL.

Example: https://carrier.example.com/payments

401

Missing or invalid API key.

application/json

404

Application not found.

application/json

422

Payment redirect not supported for this carrier.

application/json

get

/api/v1/applications/{id}/payment_redirect

GET /api/v1/applications/{id}/payment_redirect HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "application_id": "HSA000000001",
  "method": "POST",
  "endpoint": "https://carrier.example.com/payments",
  "fields": [
    {
      "name": "Partner Assigned Consumer ID",
      "value": "HSA000000001"
    },
    {
      "name": "Total Amount Owed",
      "value": "350.00"
    },
    {
      "name": "Premium Amount Total",
      "value": "350.00"
    },
    {
      "name": "First Name",
      "value": "Jane"
    },
    {
      "name": "Last Name",
      "value": "Doe"
    },
    {
      "name": "Payment Transaction ID",
      "value": "TXN789012"
    }
  ]
}

Cancel application

post

Cancels an application that is pending effectuation. Not all carriers support cancellation. Use the GET /applications/{id} response to check carrier capabilities.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Path parameters

idstringRequired

HealthSherpa application ID.

Example: HSA000000001

Body

reasonstringOptional

Reason for cancellation.

effective_datestring · dateOptional

Requested cancellation effective date.

Responses

200

Application cancelled

application/json

application_idstringOptionalExample: HSA000000001

policy_statusstringOptionalExample: cancelled

effective_datestring · date · nullableOptional

The effective date of the status change (cancellation or termination).

Example: 2026-03-01

updated_atstring · date-timeOptionalExample: 2026-02-15T10:30:00Z

400

Cancellation not allowed.

application/json

401

Missing or invalid API key.

application/json

404

Application not found.

application/json

post

/api/v1/applications/{id}/cancel

POST /api/v1/applications/{id}/cancel HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "reason": "text",
  "effective_date": "2026-03-10"
}

{
  "application_id": "HSA000000001",
  "policy_status": "cancelled",
  "effective_date": "2026-03-01",
  "updated_at": "2026-02-15T10:30:00Z"
}

Terminate policy

post

Terminates an active (effectuated) policy. Used when coverage should end before the natural expiration date.

Authorizations

x-api-keystringRequired

API key provided during onboarding.

Path parameters

idstringRequired

HealthSherpa application ID.

Example: HSA000000001

Body

reasonstringOptional

Reason for termination.

termination_datestring · dateRequired

Requested termination effective date.

Responses

200

Termination request accepted

application/json

application_idstringOptionalExample: HSA000000001

policy_statusstringOptionalExample: cancelled

effective_datestring · date · nullableOptional

The effective date of the status change (cancellation or termination).

Example: 2026-03-01

updated_atstring · date-timeOptionalExample: 2026-02-15T10:30:00Z

400

Termination not allowed.

application/json

401

Missing or invalid API key.

application/json

404

Application not found.

application/json

post

/api/v1/applications/{id}/terminate

POST /api/v1/applications/{id}/terminate HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "reason": "text",
  "termination_date": "2026-03-10"
}

{
  "application_id": "HSA000000001",
  "policy_status": "cancelled",
  "effective_date": "2026-03-01",
  "updated_at": "2026-02-15T10:30:00Z"
}

PreviousEnrollConnect NextExpanded Deeplink API

Last updated 5 days ago

hashtagOverview

hashtagBase URLs

hashtagRate Limits

hashtagError Format

hashtagHypermedia Actions (next_actions)

hashtagSubmission readiness

hashtagFuture Functionality

hashtagPayment and PCI Compliance

hashtagAPI Specification

hashtagCreate application

hashtagUpdate application

hashtagGet application

hashtagList applications (stretch for launch)

hashtagUpload supporting documentation

hashtagSubmit application

hashtagGet payment redirect data

hashtagCancel application

hashtagTerminate policy

Overview

Base URLs

Rate Limits

Error Format

Hypermedia Actions (`next_actions`)

Submission readiness

Future Functionality

Payment and PCI Compliance

API Specification

Create application

Update application

Get application

List applications (stretch for launch)

Upload supporting documentation

Submit application

Get payment redirect data

Cancel application

Terminate policy