Kota Health Insurance API
The Health Insurance API from Kota — 8 operation(s) for health insurance.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference Associated Persons Health Insurance API
version: 1.0.0
servers:
- url: https://test.api.kota.io
description: test
- url: https://api.kota.io
description: production
tags:
- name: Health Insurance
paths:
/employers/{employer_id}/health_insurance/quotes/{employer_quote_id}:
get:
tags:
- Health Insurance
summary: Retrieve employer quote
description: Returns group's health insurance `quote` for an `employer` by `employer_quote_id`.
operationId: RetrieveEmployerHealthInsuranceQuote
parameters:
- name: employer_id
in: path
required: true
schema:
pattern: er_.+
type: string
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: employer_quote_id
in: path
required: true
schema:
pattern: erhq_.+
type: string
example: erhq_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployerHealthInsuranceQuoteResponse'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/employers/{employer_id}/health_insurance/quotes:
get:
tags:
- Health Insurance
summary: List all employer quotes
description: Returns a list of health insurance `quotes` for an `employer`. The `quotes` are returned sorted by creation date, with the most recent `quote` appearing first.
operationId: ListEmployerHealthInsuranceQuotes
parameters:
- name: employer_id
in: path
required: true
schema:
pattern: er_.+
type: string
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: status
in: query
description: 'Multiple values can be provided by separating them with a comma. Allowed values are: `pending_quote`, `action_required`, `not_undertaken`, `accepted`, `pending_insurer_acceptance`.'
schema:
type: string
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
schema:
type: integer
description: The page of results to return. Defaults to 1 if not provided.
format: int32
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
schema:
type: integer
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployerHealthInsuranceQuoteResponsePagedList'
/employers/{employer_id}/health_insurance/policies/{employer_policy_id}:
get:
tags:
- Health Insurance
summary: Retrieve an employer policy
description: Retrieve group's health insurance `policy` for an `employer` by `employer_policy_id`.
operationId: RetrieveEmployerHealthInsurancePolicy
parameters:
- name: employer_id
in: path
required: true
schema:
pattern: er_.+
type: string
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: employer_policy_id
in: path
required: true
schema:
pattern: erhp_.+
type: string
example: erhp_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployerHealthInsurancePolicyResponse'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/employers/{employer_id}/health_insurance/policies:
get:
tags:
- Health Insurance
summary: List all employer policies
description: Returns a list of group health insurance `policies` for an `employer`. The `policies` are returned sorted by creation date, with the most recent `policy` appearing first.
operationId: ListEmployerHealthInsurancePolicies
parameters:
- name: employer_id
in: path
required: true
schema:
pattern: er_.+
type: string
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: status
in: query
description: 'Multiple values can be provided by separating them with a comma. Allowed values are: `scheduled`, `active`, `expired`, `cancelled`.'
schema:
type: string
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
schema:
type: integer
description: The page of results to return. Defaults to 1 if not provided.
format: int32
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
schema:
type: integer
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployerHealthInsurancePolicyResponsePagedList'
/employees/{employee_id}/health_insurance/offers/{employee_offer_id}:
get:
tags:
- Health Insurance
summary: Retrieve an employee offer
description: Retrieve group's health insurance `offer` for an `employee` by `employee_offer_id`.
operationId: RetrieveEmployeeHealthInsuranceOffer
parameters:
- name: employee_id
in: path
required: true
schema:
pattern: ee_.+
type: string
example: ee_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: employee_offer_id
in: path
required: true
schema:
pattern: eeho_.+
type: string
example: eeho_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeHealthInsuranceOfferResponse'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/employees/{employee_id}/health_insurance/offers:
get:
tags:
- Health Insurance
summary: List all employee offers
description: Returns a list of group health insurance `offers` for an `employee`. The `offers` are returned sorted by creation date, with the most recent `offer` appearing first.
operationId: ListEmployeeHealthInsuranceOffers
parameters:
- name: employee_id
in: path
required: true
schema:
pattern: ee_.+
type: string
example: ee_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
schema:
type: integer
description: The page of results to return. Defaults to 1 if not provided.
format: int32
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
schema:
type: integer
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeHealthInsuranceOfferResponsePagedList'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/employees/{employee_id}/health_insurance/policies:
get:
tags:
- Health Insurance
summary: List all employee policies
description: Returns a list of group health insurance `policies` for an `employee`. The `policies` are returned sorted by creation date, with the most recent `policy` appearing first.
operationId: ListEmployeeHealthInsurancePolicies
parameters:
- name: employee_id
in: path
required: true
schema:
pattern: ee_.+
type: string
example: ee_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: status
in: query
description: 'Multiple values can be provided by separating them with a comma. Allowed values are: `scheduled`, `active`, `expired`, `cancelled`.'
schema:
type: string
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
schema:
type: integer
description: The page of results to return. Defaults to 1 if not provided.
format: int32
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
schema:
type: integer
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeHealthInsurancePolicyResponsePagedList'
/employees/{employee_id}/health_insurance/policies/{employee_policy_id}:
get:
tags:
- Health Insurance
summary: Retrieve an employee policy
description: Retrieve group's health insurance `policy` for an `employee` by `employee_policy_id`.
operationId: RetrieveEmployeeHealthInsurancePolicy
parameters:
- name: employee_id
in: path
required: true
schema:
pattern: ee_.+
type: string
example: ee_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: employee_policy_id
in: path
required: true
schema:
pattern: eehp_.+
type: string
example: eehp_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeHealthInsurancePolicyResponse'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
EmployerHealthInsuranceQuoteResponse:
required:
- coverage_levels
- employer_id
- id
- quoted_at
- status
type: object
properties:
object:
type: string
description: The object type
readOnly: true
id:
pattern: erhq_.+
type: string
description: Unique identifier for the quote
example: erhq_3b1333d87d9d4fd6ad83ba7f6b0e951a
employer_id:
pattern: er_.+
type: string
description: The Id of the employer for which the is created
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
quoted_at:
type: string
description: Date and time the quote was created at
format: date-time
example: '2024-12-01T00:00:00Z'
status:
allOf:
- $ref: '#/components/schemas/EmployerHealthInsuranceQuoteStatus'
description: Current status of the quote
required_action:
type: 'null'
allOf:
- $ref: '#/components/schemas/HealthInsuranceRequiredActionResponse'
description: Actions required by the employer to proceed with the quote. Set only when `status` is `action_required`.
coverage_levels:
type: array
items:
$ref: '#/components/schemas/HealthInsuranceCoverageLevelResponse'
description: List of levels covered under the policy, each item representing details about the plan’s cover. Currently Kota only supports a single level of cover.
additionalProperties: false
EmployeeHealthInsuranceOfferStatus:
enum:
- action_required
- not_undertaken
- accepted
type: string
EmployerHealthInsuranceQuoteResponsePagedList:
required:
- items
- page
- page_size
- total_count
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/EmployerHealthInsuranceQuoteResponse'
description: A paginated array containing the response elements
page:
type: integer
description: The current page of the results
format: int32
example: 123
page_size:
type: integer
description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
format: int32
example: 123
total_count:
type: integer
description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
format: int32
example: 123
has_next_page:
type: boolean
description: Whether there are more pages available after this page
readOnly: true
example: true
has_previous_page:
type: boolean
description: Whether there are more pages available before this page
readOnly: true
example: true
additionalProperties: false
HealthInsuranceRequiredActionResponse:
required:
- code
- due_at
- reason
- reason_description
type: object
properties:
reason:
type: string
description: Concise reason for the required action
reason_description:
type: string
description: Description for the required action
code:
type: string
description: Identified the type of action required, not unique across health insurance providers
due_at:
type: string
description: Date and time by which the action is due, if this is not completed then the policy will not be issued.
format: date
example: '2024-12-01'
additionalProperties: false
HealthInsuranceGrossEstimationAmountResponse:
required:
- employee_contribution
- employer_contribution
- total
type: object
properties:
employee_contribution:
type: number
description: Estimated gross premium amount deducted from employee payroll
format: double
example: 123.45
employer_contribution:
type: number
description: Estimated gross premium amount paid by the employer
format: double
example: 123.45
total:
type: number
description: Total gross premium amount (sum of employee and employer contributions).
format: double
example: 123.45
additionalProperties: false
EmployeeHealthInsuranceOfferResponsePagedList:
required:
- items
- page
- page_size
- total_count
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/EmployeeHealthInsuranceOfferResponse'
description: A paginated array containing the response elements
page:
type: integer
description: The current page of the results
format: int32
example: 123
page_size:
type: integer
description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
format: int32
example: 123
total_count:
type: integer
description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
format: int32
example: 123
has_next_page:
type: boolean
description: Whether there are more pages available after this page
readOnly: true
example: true
has_previous_page:
type: boolean
description: Whether there are more pages available before this page
readOnly: true
example: true
additionalProperties: false
EmployerHealthInsurancePolicyResponse:
required:
- coverage_levels
- employer_cancellation_period_length
- employer_id
- end_date
- enrolment_type
- id
- renewal
- start_date
- status
type: object
properties:
object:
type: string
description: The object type
readOnly: true
id:
pattern: erhp_.+
type: string
description: Unique identifier for policy
example: erhp_3b1333d87d9d4fd6ad83ba7f6b0e951a
employer_id:
pattern: er_.+
type: string
description: The Id of the employer for which the policy is created
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
start_date:
type: string
description: Policy starts on this date
format: date
example: '2024-12-01'
end_date:
type: string
description: Policy ends on this date
format: date
example: '2024-12-01'
cancellation_date:
type:
- 'null'
- string
description: Policy was cancelled on this date, if cancellation occured
format: date
example: '2024-12-01'
group_policy_number:
type:
- 'null'
- string
description: Group’s health insurance policy number, if available
status:
allOf:
- $ref: '#/components/schemas/EmployerHealthInsurancePolicyStatus'
description: Current status of policy
enrolment_type:
allOf:
- $ref: '#/components/schemas/EnrolmentType'
description: Enrolment type of the policy
renewal:
allOf:
- $ref: '#/components/schemas/GetEmployerHealthPolicyRenewal'
description: Renewal information for the policy
employer_cancellation_period_length:
type: integer
description: How many days the employer has to cancel the policy since the policy starts
format: int32
example: 123
coverage_levels:
type: array
items:
$ref: '#/components/schemas/HealthInsuranceCoverageLevelResponse'
description: Represents the available coverage levels for this policy
additionalProperties: false
EmployeeHealthInsurancePolicyResponsePagedList:
required:
- items
- page
- page_size
- total_count
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/EmployeeHealthInsurancePolicyResponse'
description: A paginated array containing the response elements
page:
type: integer
description: The current page of the results
format: int32
example: 123
page_size:
type: integer
description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
format: int32
example: 123
total_count:
type: integer
description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
format: int32
example: 123
has_next_page:
type: boolean
description: Whether there are more pages available after this page
readOnly: true
example: true
has_previous_page:
type: boolean
description: Whether there are more pages available before this page
readOnly: true
example: true
additionalProperties: false
CurrencyCode:
enum:
- eur
- aed
- afn
- xcd
- all
- amd
- aoa
- ars
- usd
- aud
- awg
- azn
- bam
- bbd
- bdt
- xof
- bgn
- bhd
- bif
- bmd
- bnd
- bob
- bov
- brl
- bsd
- inr
- btn
- nok
- bwp
- byn
- bzd
- cad
- xaf
- cdf
- chf
- che
- chw
- nzd
- clp
- clf
- cny
- cop
- cou
- crc
- cup
- cuc
- cve
- ang
- czk
- djf
- dkk
- dop
- dzd
- egp
- mad
- ern
- etb
- fjd
- fkp
- mdl
- gbp
- gel
- ghs
- gip
- gmd
- gnf
- gtq
- gyd
- hkd
- hnl
- hrk
- htg
- huf
- idr
- xdr
- ils
- iqd
- irr
- isk
- jmd
- jod
- jpy
- kes
- kgs
- khr
- kmf
- kpw
- krw
- kwd
- kyd
- kzt
- lak
- lbp
- lkr
- lrd
- lsl
- zar
- lyd
- mga
- mkd
- mmk
- mnt
- mop
- mru
- mur
- mvr
- mwk
- mxn
- mxv
- myr
- mzn
- nad
- xpf
- ngn
- nio
- npr
- omr
- pab
- pen
- pgk
- php
- pkr
- pln
- pyg
- qar
- ron
- rsd
- rub
- rwf
- sar
- sbd
- scr
- sdg
- sek
- sgd
- shp
- sll
- sos
- srd
- ssp
- stn
- svc
- xsu
- syp
- twd
- szl
- thb
- tjs
- tmt
- tnd
- top
- try
- ttd
- tzs
- uah
- ugx
- usn
- uyu
- uyi
- uyw
- uzs
- ves
- vnd
- vuv
- wst
- yer
- xua
- zmw
- zwl
type: string
HealthInsuranceCoverageLevelResponse:
required:
- documents
- plan_currency
- plan_id
- plan_name
- provider_logo_url
- provider_name
type: object
properties:
plan_id:
pattern: pl_.+
type: string
description: Unique identifier for the health insurance plan
example: pl_3b1333d87d9d4fd6ad83ba7f6b0e951a
plan_name:
type: string
description: Name of the health insurance plan
plan_currency:
allOf:
- $ref: '#/components/schemas/CurrencyCode'
description: Currency code of the health insurance plan
provider_name:
type: string
description: Name of the health insurance provider
provider_logo_url:
type: string
description: Logo URL of the health insurance provider
provider_employer_platform_url:
type:
- 'null'
- string
description: URL to the health insurance provider's website for Employer Management
provider_support_phone:
type:
- 'null'
- string
description: Support phone number to the health insurance provider's website for Employer Management
documents:
type: array
items:
$ref: '#/components/schemas/HealthInsuranceCoverageLevelDocumentResponse'
description: Documents related to the health insurance plan, these documents may change at renewal, this includes the documents like `Insurance Product Information Document`, `Hospital Lists`, `Table of Cover` etc
additionalProperties: false
EmployerHealthInsurancePolicyStatus:
enum:
- scheduled
- active
- expired
- cancelled
type: string
EmployerHealthInsurancePolicyRenewalStatus:
enum:
- upcoming
- open
- renewed
- cancelled
type: string
EmployeeHealthPolicyRenewal:
required:
- decision_confirmed
- renewal_date
- status
- window_end_date
- window_start_date
type: object
properties:
status:
allOf:
- $ref: '#/components/schemas/EmployerHealthInsurancePolicyRenewalStatus'
description: The current status of the renewal
renewal_date:
type: string
description: Policy renewal date
format: date
example: '2024-12-01'
window_start_date:
type: string
description: Renewal window starts on this day
format: date
example: '2024-12-01'
window_end_date:
type: string
description: Renewal window ends at the end of this day
format: date
example: '2024-12-01'
decision_confirmed:
type: boolean
description: Whether the decision to renew the policy has been confirmed
example: true
renewed_health_insurance_id:
pattern: eehp_.+
type:
- 'null'
- string
description: The ID of the renewed health insurance policy, if renewed
example: eehp_3b1333d87d9d4fd6ad83ba7f6b0e951a
additionalProperties: false
HealthInsuranceCoverageLevelDocumentResponse:
required:
- link
- title
type: object
properties:
title:
type: string
description: Health Insurance Document Title
link:
type: string
description: Health Insurance Document Link (can be a link to a website or a file path)
additionalProperties: false
EmployeeHealthInsuranceOfferResponse:
required:
- coverage_level
- employee_id
- employer_id
- id
- status
type: object
properties:
object:
type: string
description: The object type
readOnly: true
id:
pattern: eeho_.+
type: string
description: Unique identifier for offer
example: eeho_3b1333d87d9d4fd6ad83ba7f6b0e951a
employer_id:
pattern: er_.+
type: string
description: The Id of the employer for which the offer is available
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
employee_id:
pattern: ee_.+
type: string
description: The Id of the employee for which the offer is available
example: ee_3b1333d87d9d4fd6ad83ba7f6b0e951a
external_customer_id:
type:
- 'null'
- string
description: A unique identifier assigned by the Employer of Record (EoR) platform to the Customer (i.e. the company using the EoR service) for which the employee is employed. This ID groups employees under this Customer, enabling the aggregation of contribution reporting and other values per Customer rather than per legal entity. This parameter is only available to EoR platforms.
status:
allOf:
- $ref: '#/components/schemas/EmployeeHealthInsuranceOfferStatus'
description: Current status of offer
required_action:
type: 'null'
allOf:
- $ref: '#/components/schemas/HealthInsuranceRequiredActionResponse'
description: Required action to progress the offer, if any. Set only when `status` is `action_required`.
coverage_level:
allOf:
- $ref: '#/components/schemas/HealthInsuranceCoverageLevelResponse'
description: Details about the coverage level for the offer. Only a single level of cover is available for a specific employee!
additionalProperties: false
ProblemDetails:
type: object
properties:
type:
type:
- 'null'
- string
title:
type:
- 'null'
- string
status:
type:
- 'null'
- integer
format: int32
detail:
type:
- 'null'
- string
instance:
type:
- 'null'
- string
additionalProperties: {}
EmployerHealthInsuranceQuoteStatus:
enum:
- pending_quote
- action_required
- not_undertaken
- accepted
- pending_insurer_acceptance
type: string
GetEmployerHealthPolicyRenewal:
required:
- decision_confirmed
- renewal_date
- status
- window_end_date
- window_start_date
type: object
properties:
status:
allOf:
- $ref: '#/components/schemas/EmployerHealthInsurancePolicyRenewalStatus'
description: The current status of the renewal
renewal_date:
type: string
description: Policy renewal date
format: date
example: '2024-12-01'
window_start_date:
type: string
description: Renewal window starts on this day
format: date
example: '2024-12-01'
window_end_date:
type: string
description: Renewal window ends at the end of this day
format: date
example: '2024-12-01'
decision_confirmed:
type: boolean
description: Whether the decision to renew the policy has been confirmed
example: true
renewed_health_insurance_id:
pattern: erhp_.+
type:
- 'null'
- string
description: The ID of the renewed health insurance policy, if renewed
example: erhp_3b1333d87d9d4fd6ad83ba7f6b0e951a
additionalProperties: false
EmployerHealthInsurancePolicyResponsePagedList:
required:
- items
- page
- page_size
- total_count
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/EmployerHealthInsurancePolicyResponse'
description: A paginated array containing the response elements
page:
type: integer
description: The current page of the results
format: int32
example: 123
page_size:
type: integer
description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
format: int32
example: 123
total_count:
type: integer
description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
format: int32
example: 123
has_next_page:
type: boolean
description: Whether there are more pages available after this page
readOnly: true
example: true
has_previous_page:
type: boolean
description: Whether there are more pages available before this page
readOnly: true
example: true
additionalProperties: false
EnrolmentType:
enum:
- opt_out
- opt_in
type: string
EmployeeHealthInsurancePolicyStatus:
enum:
- scheduled
- active
- expired
- cancelled
type: string
EmployeeHealthInsurancePolicyResponse:
required:
- coverage_level
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kota/refs/heads/main/openapi/kota-health-insurance-api-openapi.yml