Quickstart Guide

Clasp API basics.

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": "[e-mail]",
  "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": "[e-mail]",
  "employer": "er_123",
  "hire_date": "2024-01-08",
  "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": "2025-05-01",
    "effective_end": "2026-04-30",
    "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"
            ]
        }
    ],
       "composite_rates": {
        "member": "395.42",
        "member_spouse": "578.40",
        "member_child": "530.20",
        "member_children": "842.61",
        "member_family": "1550.67"
    }
}

6. 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"
  }
}

7. Set up a contribution strategy for the plan

POST /plan_configurations/{{claspMedicalPlanConfigurationId}}/contribution_strategy
Authorization: Bearer $CLASP_API_KEY
Content-Type: application/json

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

8. 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 [e-mail] or your dedicated solutions engineer.