Get access
DocumentationAPI ReferenceEmbed SDK Reference
  • API Reference
    • Contribution Reports
    • Events and Webhooks
    • API errors
Get access
LogoLogo
LogoLogo
API ReferenceHealth Insurance

Retrieve an employee policy

GET
/employees/:employee_id/health_insurance/policies/:employee_policy_id
GET
/employees/:employee_id/health_insurance/policies/:employee_policy_id
1curl https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a/health_insurance/policies/eehp_3b1333d87d9d4fd6ad83ba7f6b0e951a \
2     -H "Authorization: Bearer <token>"
Try it
200Retrieved
1{
2  "id": "eehp_3b1333d87d9d4fd6ad83ba7f6b0e951a",
3  "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
4  "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
5  "start_date": "2024-12-01",
6  "end_date": "2024-12-01",
7  "status": "scheduled",
8  "enrolment_type": "opt_out",
9  "renewal": {
10    "status": "upcoming",
11    "renewal_date": "2024-12-01",
12    "window_start_date": "2024-12-01",
13    "window_end_date": "2024-12-01",
14    "decision_confirmed": true,
15    "renewed_health_insurance_id": "eehp_3b1333d87d9d4fd6ad83ba7f6b0e951a"
16  },
17  "opt_out_deadline_date": "2024-12-01",
18  "coverage_level": {
19    "plan_id": "pl_3b1333d87d9d4fd6ad83ba7f6b0e951a",
20    "plan_name": "string",
21    "plan_currency": "eur",
22    "provider_name": "string",
23    "provider_logo_url": "string",
24    "documents": [
25      {
26        "title": "string",
27        "link": "string"
28      }
29    ],
30    "provider_employer_platform_url": "string",
31    "provider_support_phone": "string"
32  },
33  "enrolled_dependants_count": 123,
34  "estimated_gross_premium": {
35    "currency": "eur",
36    "monthly": {
37      "employee_contribution": 123,
38      "employer_contribution": 123,
39      "total": 123
40    },
41    "term": {
42      "employee_contribution": 123,
43      "employer_contribution": 123,
44      "total": 123
45    }
46  },
47  "object": "string",
48  "external_customer_id": "string",
49  "cancellation_date": "2024-12-01",
50  "policy_number": "string"
51}
Retrieve group's health insurance `policy` for an `employee` by `employee_policy_id`.
Was this page helpful?
Previous

Contribution Reports

Access and process insurance contributions across multiple countries
Next
Built with
Contribution Reports
Access and process insurance contributions across multiple countries

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Path parameters

employee_idstringRequiredformat: "ee_.+"
employee_policy_idstringRequiredformat: "eehp_.+"

Response

OK
idstringformat: "eehp_.+"
Unique identifier for policy
employer_idstringformat: "er_.+"
The Id of the employer for which the policy is created
employee_idstringformat: "ee_.+"
The Id of the employee for which the policy is created
start_datestringformat: "date"
Policy starts on this date
end_datestringformat: "date"
Policy ends on this date
statusenum
Current status of policy
Allowed values:
enrolment_typeenum
Enrolment type of the policy
Allowed values:
renewalobject
Renewal information for the policy
opt_out_deadline_datestringformat: "date"
Last day to opt out from the policy
coverage_levelobject
Represents the current coverage level for the policy
enrolled_dependants_countinteger
Number of dependants (spouse, children, or other eligible family members) currently enrolled in this health insurance policy.
estimated_gross_premiumobject
Estimated gross premium amounts for this health insurance policy based on current enrollment and policy configuration. Important: These estimates are for planning purposes only and may differ from actual billed amounts due to life events, policy changes, insurer billing practices, or timing adjustments. For accurate payroll amounts, use the Contribution Reporting API.
objectstring or null
The object type
external_customer_idstring or null
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.
cancellation_datestring or nullformat: "date"
Policy was cancelled on this date, if cancellation occured
policy_numberstring or null
Health insurance policy number, if available

Errors

Policy ends on this date
Current status of policy
Enrolment type of the policy
Renewal information for the policy
Last day to opt out from the policy
Represents the current coverage level for the policy
The object type
Policy was cancelled on this date, if cancellation occured
Health insurance policy number, if available
Authorization header using the Bearer scheme
OK

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.

Retrieve group’s health insurance policy for an employee by employee_policy_id.

Number of dependants (spouse, children, or other eligible family members) currently enrolled in this health insurance policy.

Estimated gross premium amounts for this health insurance policy based on current enrollment and policy configuration. Important: These estimates are for planning purposes only and may differ from actual billed amounts due to life events, policy changes, insurer billing practices, or timing adjustments. For accurate payroll amounts, use the Contribution Reporting API.