Thatch Employers API

openapi: 3.1.0
info:
  title: Thatch for Platforms Deductions Employers API
  version: v1
  description: Thatch for Platforms is a set of REST APIs and embeddable JavaScript components that let partners bring ICHRA (Individual Coverage Health Reimbursement Arrangement) benefits to their customers. Partners onboard employers, manage employees, run the employer onboarding flow through an embedded iframe, track enrollments and members, model pay schedules, and retrieve payroll deductions. Access is limited to approved partners; contact platforms@thatch.com to set up an account and generate an API key in the Thatch dashboard.
  contact:
    name: Thatch for Platforms
    email: platforms@thatch.com
    url: https://docs.thatch.com/
  x-apisjson-generated: '2026-07-21'
  x-apisjson-method: generated
  x-apisjson-source: https://docs.thatch.com/api/
servers:
- url: https://partners.thatchcloud.com/api/partners/v1
  description: Production
security:
- Bearer: []
tags:
- name: Employers
  description: Platforms onboard employers into Thatch, and have employees enrolled in plans.
paths:
  /employers:
    post:
      tags:
      - Employers
      operationId: createEmployer
      summary: Create an employer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployerCreate'
      responses:
        '201':
          description: Create an employer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employer'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      tags:
      - Employers
      operationId: listEmployers
      summary: List employers
      parameters:
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: List employers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employer'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employers/{employer_id}:
    parameters:
    - name: employer_id
      in: path
      required: true
      description: Employer ID
      schema:
        type: string
    get:
      tags:
      - Employers
      operationId: getEmployer
      summary: Get an employer
      responses:
        '200':
          description: Get an employer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Employers
      operationId: updateEmployer
      summary: Update an employer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployerUpdate'
      responses:
        '200':
          description: Update an employer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    PageNumber:
      name: page[number]
      in: query
      description: Page number
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
    PageSize:
      name: page[size]
      in: query
      description: Number of items per page. Must be between 1 and 1,000 (inclusive). Defaults to 20.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 20
  responses:
    NotFound:
      description: The requested resource was not found.
    Unauthorized:
      description: Authentication failed or API key missing/invalid.
  schemas:
    Employer:
      type: object
      properties:
        id:
          type: string
          example: empl_01j2j3smtwx656y2tbqm7ty6gr
        onboarding_status:
          type: string
          example: employees_invited
        name:
          type: string
        business_type:
          type: string
        ein:
          type: string
        dba:
          type: string
        address_line1:
          type: string
        address_line2:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        phone_number:
          type: string
        industry:
          type: string
          example: professional_scientific_and_technical_services
        lifecycle_events:
          type: array
          items:
            $ref: '#/components/schemas/LifecycleEvent'
        pay_schedules:
          type: array
          items:
            $ref: '#/components/schemas/PaySchedule'
        pricing:
          $ref: '#/components/schemas/EmployerPricing'
        metadata:
          $ref: '#/components/schemas/Metadata'
    CurrentHealthInsurance:
      type: object
      description: Current health insurance plan details
      properties:
        individual_deductible:
          type: integer
          example: 1500
        individual_oop_max:
          type: integer
          example: 5000
        network_type:
          type: string
          example: hmo
        metal_tier:
          type: string
          example: silver
    EmployerCreate:
      type: object
      required:
      - address_line1
      - business_type
      - city
      - ein
      - email
      - name
      - state
      - zip
      properties:
        address_line1:
          type: string
          description: Employer's address (line 1)
        business_type:
          type: string
          enum:
          - c_corp
          - s_corp
          - llc
          - llp
          - partnership
          - sole_proprietorship
          - non_profit
          description: Employer's business type
        city:
          type: string
          description: Employer's city
        ein:
          type: string
          description: Employer's EIN (Employer Identification Number)
        email:
          type: string
          description: Email address for the employer's administrator
        name:
          type: string
          description: Employer's legal business name
        state:
          type: string
          description: Employer's state (USPS two-letter code)
          enum:
          - AK
          - AL
          - AR
          - AZ
          - CA
          - CO
          - CT
          - DC
          - DE
          - FL
          - GA
          - HI
          - IA
          - ID
          - IL
          - IN
          - KS
          - KY
          - LA
          - MA
          - MD
          - ME
          - MI
          - MN
          - MO
          - MS
          - MT
          - NC
          - ND
          - NE
          - NH
          - NJ
          - NM
          - NV
          - NY
          - OH
          - OK
          - OR
          - PA
          - RI
          - SC
          - SD
          - TN
          - TX
          - UT
          - VA
          - VT
          - WA
          - WI
          - WV
          - WY
        zip:
          type: string
          description: Employer's ZIP code
          with optional +4: null
        dba:
          type: string
          description: Employer's DBA name
          if different from the legal business name: null
        industry_code:
          type: string
          description: 'Employer''s industry NAICS code (2-6 digits). Valid prefixes are: 11, 21, 22, 23, 31, 32, 33, 42, 44, 45, 48, 49, 51, 52, 53, 54, 55, 56, 61, 62, 71, 72, 81, 92'
        address_line2:
          type: string
          description: Employer's address (line 2)
        phone_number:
          type: string
          description: Employer's phone number
        first_name:
          type: string
          description: First name of the employer administrator
        last_name:
          type: string
          description: Last name of the employer administrator
        offers_health_insurance_today:
          type: boolean
          description: Whether the employer offers health insurance today
        current_health_insurance:
          $ref: '#/components/schemas/CurrentHealthInsurance'
        coverage_start_date:
          type: string
          format: date
          description: The desired start date for the employer's new health insurance coverage
        pricing:
          $ref: '#/components/schemas/EmployerPricing'
        metadata:
          $ref: '#/components/schemas/Metadata'
    PaySchedule:
      type: object
      properties:
        id:
          type: string
          example: paysch_1234
        name:
          type: string
          example: Bi-Weekly Payroll
        reference_pay_date:
          type: string
          format: date
          deprecated: true
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        frequency:
          type: string
          example: bi_weekly
        first_day:
          type: integer
          deprecated: true
        second_day:
          type: integer
          deprecated: true
        bank_closure_strategy:
          type: string
          example: before
        remote_id:
          type: string
          example: remote_123
        active:
          type: boolean
    EmployerPricing:
      type: object
      description: The monthly pricing for the employer. Must be greater than the expected commission.
      properties:
        platform_fee:
          $ref: '#/components/schemas/Money'
    Money:
      type: object
      description: A monetary amount in minor units with an ISO 4217 currency code.
      properties:
        amount:
          type: integer
          description: Amount in the smallest currency unit (e.g. cents).
        currency_code:
          type: string
          example: USD
    EmployerUpdate:
      type: object
      properties:
        offers_health_insurance_today:
          type: boolean
        current_health_insurance:
          $ref: '#/components/schemas/CurrentHealthInsurance'
        coverage_start_date:
          type: string
          format: date
        pricing:
          $ref: '#/components/schemas/EmployerPricing'
        metadata:
          $ref: '#/components/schemas/Metadata'
    LifecycleEvent:
      type: object
      properties:
        id:
          type: string
          example: lcevent_01j2j3smtwx656y2tbqm7ty6gr
        event_type:
          type: string
          example: employees_invited
        timestamp:
          type: string
          format: date-time
    Metadata:
      type: object
      description: Set of key-value pairs that you can attach to an API resource for storing additional structured information. Individual keys can be unset by posting an empty string value; all keys can be unset by posting an empty object.
      additionalProperties:
        type: string
    Pagination:
      type: object
      properties:
        total_records:
          type: integer
          example: 25
        current_page:
          type: integer
          example: 1
        total_pages:
          type: integer
          example: 3
        next_page:
          type: integer
          example: 2
        prev_page:
          type: integer
          example: 0
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: 'All requests are authenticated with your API key using Bearer token authentication. Include the header `Authorization: Bearer <YOUR_API_KEY>`. Generate an API key in the Thatch dashboard.'