Quickstart Guide

1. Prerequisites

What	Why
Clasp API key	Used as a Bearer token from your backend to call the API and mint component links.

Never expose your long‑lived API key in the browser.
All API calls that use the Bearer key should originate server‑side.

2. Create an employer

POST /employers
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

{
  "legal_name": "Example Legal Name",
  "trade_name": "Example Trade Name",
  "external_id": "payroll_provider_company_id",
  "email": "company@domain.com",
  "address": {
    "line1": "1600 Pennsylvania Ave",
    "city": "Washington",
    "state": "DC",
    "zip_code": "20500"
  }
}

The response includes an id such as er_123. Persist this for future calls.

3. Create an employee (members)

POST /members
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1990-05-16",
  "ssn": "123456789",
  "email": "jane.doe@domain.com",
  "employer": "er_123",
  "address": {
    "line1": "1600 Pennsylvania Avenue NW",
    "city": "Washington",
    "state": "DC",
    "zip_code": "20500"
  },
  "hire_date": "2026-11-05",
  "hours_worked": 40,
  "pay_frequency": "biweekly"
}

Save the returned member id (e.g., mem_456).

4. Create a group structure

POST /groups
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

{
  "group_number": "1324234",
  "carrier": "carr_xOvpBqHA75scQCtcHNfLS",
  "employer": "{{claspEmployerId}}"
}

5. Create a plan

POST /plans
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

{
    "termination_policy": "termination_date",
    "waiting_period": "First of Month after 30 Days",
    "plan_name": "Platinum HMO",
    "plan_type": "hmo",
    "line_of_coverage": "medical",
    "group": "{{claspGroupId}}",
    "premium_type": "composite",
    "effective_start": "2026-11-01",
    "effective_end": "2027-10-31",
    "requires_primary_care_provider": true,
    "plan_details": [
        {
            "label": "Medical Deductible",
            "tooltip": "The amount that you must pay before your health plan begins to pay or contribute for any medical services.",
            "info_lines": [
                "Individual: $1,250",
                "Family: $2,500"
            ]
        },
        {
            "label": "Pharma Deductible",
            "tooltip": "The amount that you must pay before your health plan begins to pay or contribute for any prescriptions.",
            "info_lines": [
                "Individual: $0",
                "Family: $0"
            ]
        },
        {
            "label": "Physician Visit",
            "tooltip": "The fixed amount that you will contribute towards physician visits.",
            "info_lines": [
                "Primary: $35/visit",
                "Specialist: $60/visit"
            ]
        },
        {
            "label": "Out-of-pocket Max",
            "tooltip": "The limit on the amount you are obligated to pay during the plan year for any treatment that is covered by your plan.",
            "info_lines": [
                "Individual: $8,600",
                "Family: $17,200"
            ]
        }
    ]
}

6. Add plan premiums

Replace {{claspMedicalPlanId}} with the plan’s returned id. Add the premiums before opening the employee component or requesting eligible plans.

POST /plans/{{claspMedicalPlanId}}/premiums
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

[
  {
    "coverage_type": "member",
    "amount": "395.42"
  },
  {
    "coverage_type": "member_spouse",
    "amount": "578.40"
  },
  {
    "coverage_type": "member_child",
    "amount": "530.20"
  },
  {
    "coverage_type": "member_children",
    "amount": "842.61"
  },
  {
    "coverage_type": "member_family",
    "amount": "1550.67"
  }
]

7. Define a plan configuration

POST /plan_configurations
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

{
  "plan": "{{claspMedicalPlanId}}",
  "termination_policy": "termination_date",
  "waiting_period": {
    "duration": 0,
    "period": "day",
    "policy": "end_of_waiting_period"
  }
}

8. Set up a contribution strategy for the plan

This example uses API version 2026-04-24. See Versioning for how to select an API version.

POST /plan_configurations/{{claspMedicalPlanConfigurationId}}/contribution_strategy
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json
Clasp-Version: 2026-04-24

{
  "strategy_type": "benefit_split",
  "employer_contribution": {
    "member": {
      "contribution_type": "employer_percentage",
      "contribution": "80",
      "monthly_min_threshold": "5",
      "monthly_max_threshold": "1200"
    },
    "member_spouse": {
      "contribution_type": "employer_percentage",
      "contribution": "50",
      "monthly_min_threshold": "5",
      "monthly_max_threshold": "1200"
    },
    "member_child": {
      "contribution_type": "employer_percentage",
      "contribution": "50",
      "monthly_min_threshold": "5",
      "monthly_max_threshold": "1200"
    },
    "member_children": {
      "contribution_type": "employer_percentage",
      "contribution": "30",
      "monthly_min_threshold": "5",
      "monthly_max_threshold": "1200"
    },
    "member_family": {
      "contribution_type": "employer_percentage",
      "contribution": "25",
      "monthly_min_threshold": "5",
      "monthly_max_threshold": "1200"
    }
  }
}

9. Generate an Employee Component magic link

POST /components/member
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

{ "member": "mem_456" }

Response

{ "url": "https://benefits.withclasp.com/?otp_token=•••" }

Congrats! You’ve just set up your first plan. Open the magic link you just generated to enroll in the plan. Need help? Ping us at support@withclasp.com or your dedicated solutions engineer.

General

General Guides

API Usage Guides

API Reference

1. Prerequisites

2. Create an employer

3. Create an employee (members)

4. Create a group structure

5. Create a plan

6. Add plan premiums

7. Define a plan configuration

8. Set up a contribution strategy for the plan

9. Generate an Employee Component magic link