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.
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"
}
}
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",
"hire_date": "2024-01-08",
"hours_worked": 40,
"pay_frequency": "biweekly"
}
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" }
{ "url": "https://benefits.withclasp.com/?otp_token=•••" }