Thatch for Platforms quickstart guide

Thatch for Platforms enables partners to build an embedded health insurance experience into their applications. Using a combination of REST APIs and JavaScript components, you can deliver a complete health benefits solution for employers and their employees.

Thatch for Platforms provides a few core capabilities:

Authentication and authorization
Employer onboarding
Employee management

This guide walks through implementing these features in your application. You can also view the full API documentation.

Prerequisites

Thatch for Platforms is only available to specific partners. Get in touch with us at platforms@thatch.com to set up an account.

All requests made to the Thatch API are authenticated and authorized using your API key. Once you have a Thatch account, you can generate an API key in the Thatch dashboard.

Thatch uses Bearer Token authentication in its APIs. In all API requests to Thatch, include this HTTP header:

Authorization: Bearer <YOUR_API_KEY>

Create the employer

The first step to enrolling an employer in Thatch health benefits is to create the employer profile in Thatch. Provide all the required information, collected by your platform, through the POST /employers endpoint:

curl https://partners.thatchcloud.com/api/partners/v1/employers \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -d '{
        "email": "admin@acme.test",
        "name": "Acme Corp",
        "business_type": "c_corp",
        "ein": "12-3456789",
        "dba": "Acme",
        "address_line1": "123 Main St",
        "address_line2": "",
        "city": "San Francisco", 
        "state": "CA",
        "zip": "94108",
        "phone_number": "415-555-1212"
    }'

The API responds to a successful request with JSON data that includes the generated employer ID for use in the employer onboarding flow.

{
    "id": "empl_01j2j3smtwx656y2tbqm7ty6gr",
    "email": "admin@acme.test",
    "name": "Acme Corp",
    "business_type": "c_corp",
    "ein": "12-3456789",
    "dba": "Acme",
    "address_line1": "123 Main St",
    "address_line2": "",
    "city": "San Francisco", 
    "state": "CA",
    "zip": "94108",
    "phone_number": "415-555-1212"
}

Create employees

Using the employer_id, create an employee object for each employee using the POST /employees endpoint. Employee data is used during the employer’s quoting process, so it’s important that as much available data is sent to Thatch as possible.

Note that the dependents array is optional, but if it exists, each object in the array must contain values for date_of_birth and relationship.

curl https://partners.thatchcloud.com/api/partners/v1/employees \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -d '{
        "employer_id": "empl_01j2j3smtwx656y2tbqm7ty6gr",
        "personal_email": "beatriz.peel@gmail.test",
        "work_email": "bpeel@acme.test",
        "first_name": "Beatriz",
        "last_name": "Peel",
        "date_of_birth": "1994-01-23",
        "zip": "94102",
        "dependents": [
            {
                "relationship": "spouse",
                "date_of_birth": "1995-05-24"
            }
        ],  
        "employment_subtype": "full_time",
        "pay_type": "salary",
        "start_date": "2025-04-01"
    }'

Implement the employer onboarding flow

Almost all of the employer onboarding work is handled by Thatch, using an embeddable iframe for seamless integration into your product. Simply create an onboarding session, embed the iframe, and handle the redirect event.

Create a secure session.

Create a secure session through the POST /employer_onboarding_sessions endpoint:

curl https://partners.thatchcloud.com/api/partners/v1/employer_onboarding_sessions \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <YOUR_API_KEY>' \
    -d '{ "employer": "empl_01j2j3smtwx656y2tbqm7ty6gr" }'

The API responds to a successful request with JSON data that includes a claim_url, to be provided to the iframe.

Embed the onboarding iframe in your product.
```
<iframe
id="thatch-employer-onboarding"
title="Thatch employer onboarding"
src="<%= claim_url %>"
/>
```
The iframe handles all of the onboarding logic and data collection.
Handle the redirect event.
When the employer finalizes their allowances, the iframe sends an event to the parent window. You should catch this event and redirect the parent window to the specified URL.
```
window.addEventListener('message', handleMessage, false);
function handleMessage(event) {
    var eventData = event.data;
    switch(eventData.type) {
        case 'THATCH_REDIRECT':
            window.parent.location.href = eventData.payload.redirectUrl;
        break;
    }
}
```
At this point, the employer is redirected to Thatch to create their Thatch account, connect a bank account, and invite their employees.

Retrieve deductions

For any employees who choose plans with premiums greater than their provided allowance, deductions must be created in your payroll provider. A list of an employer’s required monthly deductions is made available through the GET /deductions endpoint five days prior to the end of each month.

curl -X GET https://partners.thatchcloud.com/api/partners/v1/deductions \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_API_KEY>' \
    -d '{
        "employer_id": "empl_01j2j3smtwx656y2tbqm7ty6gr",
        "periods": {
            "start_after": "2025-05-01"
        }
    }'

Prerequisites​

Create the employer​

Create employees​

Implement the employer onboarding flow​

Retrieve deductions​

Prerequisites

Create the employer

Create employees

Implement the employer onboarding flow

Retrieve deductions