> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server. # Retrieve a group policy GET https://test.api.kota.io/group_policies/{group_policy_id} Retrieves a `group_policy` object. Reference: https://docs.kota.io/api-reference/group-policies/retrieve-group-policy ## Authentication - `Authorization` header (bearer token, required) — Authorization header using the Bearer scheme ## Servers - `https://test.api.kota.io` (test, default) - `https://api.kota.io` (production) ## Request ### Path parameters - `group_policy_id` (string, required) ### Headers - `X-Platform-Id` (string, optional) — The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers. ## Response ### 200 OK - `id` (string, required) — Unique identifier for the group policy. Prefixed with `gp_`. - `start_date` (date, required) — Policy start (effective) date in ISO 8601 (YYYY-MM-DD). - `status` (enum, required) — Current lifecycle state of the `group_policy`, indicating its progress from creation to activation. Possible values are: - `scheduled`: Group policy has been scheduled for activation. - `active`: Group policy is now active - `expired`: Group policy is no longer active as it reached its end date - `cancelled`: Group policy is now cancelled for any reason. - Allowed values: `scheduled`, `active`, `expired`, `cancelled` - `type` (enum, required) — Policy type. Determines which sub-object is populated. - Allowed values: `health_insurance`, `life_assurance` - `provider` (PolicyProviderResponse, required) — Provider information for this policy. - `plan` (PolicyPlanResponse, required) — Plan information for this policy - `linked_group_policy_ids` (list of string, required) — The other `group_policy` objects bought together with this one as a single scheme — the policies created from the same multi-level purchase. Always present, and empty for a policy with no siblings. - `disclosures` (list of DisclosureResponse, required) — Disclosures associated with this group policy. - `group_id` (string, optional) — Identifier for the group associated with this group policy. - `employer_id` (string, optional) — Identifier for the employer associated with this group policy. - `end_date` (date, optional, nullable) — Policy end date (inclusive) in ISO 8601 (YYYY-MM-DD), or null if open-ended. - `cancellation_date` (date, optional, nullable) — Policy cancellation date (inclusive) in ISO 8610 (YYYY-MM-DD), or null if not applicable. - `health_insurance` (HealthInsuranceGroupPolicyResponse, optional) — Health insurance–specific fields (present when `type=health_insurance`). - `life_assurance` (LifeAssuranceGroupPolicyResponse, optional) — Life assurance–specific fields (present when `type=life_assurance`). - `object` (string, optional) — The object type ## Errors ### 404 Not Found Error Not Found - `type` (string, optional, nullable) - `title` (string, optional, nullable) - `status` (integer, optional, nullable) - `detail` (string, optional, nullable) - `instance` (string, optional, nullable) ## Types ### PolicyProviderResponse - `id` (string, required) — Unique identifier for the provider. Prefixed with pr_. - `name` (string, required) — Provider display name. - `description` (string, required) — Short description of the provider. - `logo_url` (string, required) - `employer_portal_url` (string, optional, nullable) — URL for the employer portal. - `employee_portal_url` (string, optional, nullable) — URL for the employee portal (may include claims management). - `support_phone_number` (string, optional, nullable) — Provider support phone number in E.164 format. ### PolicyPlanResponse - `id` (string, required) — Unique identifier for the plan. Prefixed with pl_. - `name` (string, required) — Plan display name. - `description` (string, required) — Short description of the plan. - `currency` (enum, required) — ISO 4217 currency code for pricing under this plan. - Allowed values: `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` - `documents` (list of PlanDocumentResponse, required) — List of plan documents (e.g., IPIDs, T&Cs). - `coverage_options` (list of PlanCoverageResponse, optional, nullable) — The coverage options chosen for this policy, as whole objects rather than ids. Each entry is one coverage decision from the plan's catalogue, with `options` narrowed to what was actually selected at every level. Null when nothing was selected, and null on surfaces where the selection has not been made yet. ### DisclosureResponse - `category` (enum, required) — The category of the disclosure. - Allowed values: `regulatory`, `provider`, `intermediary` - `type` (enum, required) — The specific type of disclosure within its category. - Allowed values: `intermediary_role`, `intermediary_commission`, `underwriter_disclaimer`, `anti_selection_notice`, `statement_of_needs`, `product_information`, `pre_existing_conditions`, `statutory_warning`, `privacy_policy`, `terms_of_business` - `text` (string, required) — The disclosure statement text. It may contain `{token}` placeholders, each of which has exactly one entry in `links` and must be rendered as an anchor to that link. A disclosure with no links contains no placeholders, so plain text stays plain text. - `links` (list of DisclosureLinkResponse, required) — The documents `text` names, one per placeholder it carries. Empty for a disclosure that is text only. ### HealthInsuranceGroupPolicyResponse - `renewal` (HealthInsurancePolicyRenewalResponse, required) — Renewal information for the policy. - `configuration` (HealthInsuranceGroupPolicyConfigurationResponse, required) — How the policy is configured by default, such as cost sharing and other options. - `group_policy_number` (string, optional, nullable) — Provider-issued policy number. May be null if not yet issued. ### LifeAssuranceGroupPolicyResponse - `renewal` (LifeAssurancePolicyRenewalResponse, required) — Renewal information for the policy. - `configuration` (LifeAssuranceGroupPolicyConfigurationResponse, required) — How the policy is configured by default, such as cost sharing and other options. - `group_policy_number` (string, optional, nullable) — Provider-issued policy number. May be null if not yet issued. ### PlanDocumentResponse - `title` (string, required) — Title of the document. - `link` (string, required) — Public URL to the document. This could be any format (PDF, HTML, etc.). - `type` (enum, optional) — Machine-readable document kind used for display and i18n. Possible values are listed below; as this enum can expand with new benefits, unknown values MUST be handled gracefully by clients (fallback to a generic `document` label). - Allowed values: `ipid`, `table_of_cover`, `waiting_periods`, `hospital_list`, `plan_summary`, `terms_and_conditions`, `other` ### PlanCoverageResponse - `id` (string, required) — Unique identifier for the coverage selection. Prefixed with `pc_`. - `name` (string, required) — Title for this coverage selection. Typically used as the display heading. - `scope` (enum, required) — Scope of selection for this coverage selection: `group_policy` (employer selects for the group), `policy` (per-policy selection), or `member` (individual member selects). - Allowed values: `group_policy`, `policy`, `member` - `input_type` (enum, required) — Describes whether this input allows selecting a single option or multiple options. - Allowed values: `single_select`, `multi_select` - `required` (boolean, required) — Whether a selection is mandatory. - `options` (list of PlanCoverageOptionResponse, required) — Available options within this coverage selection. - `description` (string, optional, nullable) — Full description of this coverage selection. - `min_selections` (integer, optional, nullable) — Minimum required selections (multi-select only). - `max_selections` (integer, optional, nullable) — Maximum allowed selections (multi-select only). - `sort_order` (integer, optional, nullable) — Display ordering hint. - `group_label` (string, optional, nullable) — Optional grouping label for UI rendering. Indicates which coverage selections are best presented together from a UX standpoint. ### DisclosureLinkResponse - `token` (string, required) — The placeholder this link fills. It appears in the disclosure's `text` wrapped in braces, as `{token}`, and matches `^[a-z][a-z0-9_]*$`. Tokens are unique within one disclosure, and every token in the text has exactly one link here. - `type` (enum, required) — What kind of document this is, for reporting and audit. The token is derived from it, so the two always agree; this is the value to branch on rather than matching the token as a string. - Allowed values: `intermediary_role`, `intermediary_commission`, `underwriter_disclaimer`, `anti_selection_notice`, `statement_of_needs`, `product_information`, `pre_existing_conditions`, `statutory_warning`, `privacy_policy`, `terms_of_business` - `label` (string, required) — The anchor text to display in place of the token. - `url` (string, required) — Absolute HTTPS URL of the document. - `version` (string, required) — Version of the document at the URL, so a record of what was shown can name the exact document the customer could have read. ### HealthInsurancePolicyRenewalResponse - `renewal_date` (date, required) — Renewal date. - `window_start_date` (date, required) — Renewal window start (inclusive). - `window_end_date` (date, required) — Renewal window end (inclusive). - `status` (enum, required) — Current renewal status. - Allowed values: `upcoming`, `open`, `renewed`, `cancelled` - `renewed_policy_id` (string, optional, nullable) — Identifier of the renewed policy. This means existing policy will be replaced by the renewed policy on the renewal date. ### HealthInsuranceGroupPolicyConfigurationResponse - `cost_sharing` (CostSharingConfigurationResponse, required) — Defines how the policies total cost is shared between employer and employee. ### LifeAssurancePolicyRenewalResponse - `renewal_date` (date, required) — Renewal date. - `window_start_date` (date, required) — Renewal window start (inclusive). - `window_end_date` (date, required) — Renewal window end (inclusive). - `status` (enum, required) — Current renewal status. - Allowed values: `upcoming`, `open`, `renewed`, `cancelled` - `renewed_policy_id` (string, optional, nullable) — Identifier of the renewed policy. This means existing policy will be replaced by the renewed policy on the renewal date. ### LifeAssuranceGroupPolicyConfigurationResponse - `cost_sharing` (CostSharingConfigurationResponse, required) — Defines how the policies total cost is shared between employer and employee. A life assurance policy only ever carries `policyholder_only` or `percentage`. ### PlanCoverageOptionResponse - `id` (string, required) — Unique identifier for this coverage option. Prefixed with `pco_`. - `name` (string, required) — Display name for this coverage option. - `description` (string, optional, nullable) — Longer explanation of this coverage option. - `learn_more_url` (string, optional, nullable) — Link to learn more about this coverage option. - `from_price` (double, optional, nullable) — Lowest applicable monthly price for this coverage option. - `benefits` (list of PlanCoverageOptionBenefitResponse, optional, nullable) — Benefit items included with this coverage option. - `sub_options` (list of PlanCoverageOptionResponse, optional, nullable) — Nested sub-options available when this option is selected. - `eligibility_criteria` (list of EmployerEligibilityCriterionResponse, optional, nullable) — Eligibility criteria that must be met to select this coverage option. ### CostSharingConfigurationResponse - `type` (enum, required) — Cost sharing type. Determines which sub-object is populated. - Allowed values: `member_count`, `member_selection`, `member_selection_percentage_based`, `percentage`, `policyholder_only`, `family_type`, `fixed_amount`, `full_coverage` - `member_count` (MemberCountCostSharingConfigurationResponse, optional) — Numbers of additional members covered by the employer. - `member_selection` (MemberSelectionCostSharingConfigurationResponse, optional) — Whether specific member types are covered by the employer. - `member_selection_percentage_based` (MemberSelectionPercentageBasedCostSharingConfigurationResponse, optional) — Whether specific member types are covered by the employer, each at a percentage of their premium. - `percentage` (PercentageCostSharingConfigurationResponse, optional) — Percentage of the premium the employer covers. - `family_type` (FamilyTypeCostSharingConfigurationResponse, optional) — Type of the family covered by the employer. - `fixed_amount` (FixedAmountCostSharingConfigurationResponse, optional) — Fixed monthly amount the employer covers. ### PlanCoverageOptionBenefitResponse - `name` (string, required) — Benefit name. - `description` (string, optional, nullable) — Benefit description. ### EmployerEligibilityCriterionResponse - `type` (enum, required) — The type of eligibility criterion. - Allowed values: `employees_count`, `members_count`, `industry_exclusions` - `description` (string, required) — Human-readable description of the criterion. - `employees_count` (EmployeesCountDetails, optional) — Employee count constraints. Only populated when type is `employees_count`. - `members_count` (MembersCountDetails, optional) — Member count constraints. Only populated when type is `members_count`. - `industry_exclusions` (IndustryExclusionsDetails, optional) — Industry exclusion details. Only populated when type is `industry_exclusions`. ### MemberCountCostSharingConfigurationResponse - `adults` (integer, required) — Number of additional adults covered, including partner/spouse. - `children` (integer, required) — Number of additional children covered. ### MemberSelectionCostSharingConfigurationResponse - `partner` (boolean, required) — If a spouse/partner is covered. - `children` (boolean, required) — If children are covered. ### MemberSelectionPercentageBasedCostSharingConfigurationResponse - `partner` (boolean, required) — If a spouse/partner is covered. - `children` (boolean, required) — If children are covered. - `percentage` (integer, required) — Employer coverage percentage of each covered member's premium: For 40% send 40. For 100% send 100. ### PercentageCostSharingConfigurationResponse - `percentage` (integer, required) — Employer coverage percentage: For 40% send 40. For 100% send 100. ### FamilyTypeCostSharingConfigurationResponse - `type` (enum, required) — Employer coverage family type - Allowed values: `single`, `couple`, `single_with_children`, `family` ### FixedAmountCostSharingConfigurationResponse - `monthly_amount` (double, required) — Monthly amount the employer covers, in the plan's currency. Must be positive. ### EmployeesCountDetails - `min` (integer, optional, nullable) — Minimum number of employees required. - `max` (integer, optional, nullable) — Maximum number of employees allowed. ### MembersCountDetails - `min` (integer, optional, nullable) — Minimum number of members required. - `max` (integer, optional, nullable) — Maximum number of members allowed. ### IndustryExclusionsDetails - `excluded_industries` (list of string, required) — List of excluded industries. ## Examples **Response** ```json { "id": "gp_3b1333d87d9d4fd6ad83ba7f6b0e951a", "start_date": "2024-12-01", "status": "scheduled", "type": "health_insurance", "provider": { "id": "pr_3b1333d87d9d4fd6ad83ba7f6b0e951a", "name": "string", "description": "string", "logo_url": "string", "employer_portal_url": null, "employee_portal_url": null, "support_phone_number": null }, "plan": { "id": "pl_3b1333d87d9d4fd6ad83ba7f6b0e951a", "name": "string", "description": "string", "currency": "eur", "documents": [ { "title": "string", "link": "string", "type": "ipid" } ], "coverage_options": null }, "linked_group_policy_ids": [ "gp_3b1333d87d9d4fd6ad83ba7f6b0e951a" ], "disclosures": [ { "category": "regulatory", "type": "intermediary_role", "text": "string", "links": [ { "token": "string", "type": "intermediary_role", "label": "string", "url": "string", "version": "string" } ] } ], "group_id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a", "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "end_date": "2024-12-01", "cancellation_date": "2024-12-01", "health_insurance": null, "life_assurance": null, "object": "string" } ``` **SDK Code** ```python import requests url = "https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.kota.io/group_policies/gp_3b1333d87d9d4fd6ad83ba7f6b0e951a")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```