---
title: "Retrieve a group policy"
method: GET
path: "/group_policies/{group_policy_id}"
tags: ["Group Policies"]
---

# Retrieve a group policy

`GET /group_policies/{group_policy_id}`

## Request

- Base URL: `https://test.api.kota.io`
- URL: `https://test.api.kota.io/group_policies/{group_policy_id}`
- Auth: HTTP bearer

Retrieves a `group_policy` object.

## Path parameters

- `group_policy_id` string, required

## Response `200`

OK

- GroupPolicyResponse
  - `id` string, required: Unique identifier for the group policy. Prefixed with `gp_`.
  - `group_id` string: Identifier for the group associated with this group policy.
  - `employer_id` string: Identifier for the employer associated with this group policy.
  - `start_date` string, date, required: Policy start (effective) date in ISO 8601 (YYYY-MM-DD).
  - `end_date` string, date, nullable: Policy end date (inclusive) in ISO 8601 (YYYY-MM-DD), or null if open-ended.
  - `cancellation_date` string, date, nullable: Policy cancellation date (inclusive) in ISO 8610 (YYYY-MM-DD), or null if not applicable.
  - `status` 'scheduled' | 'active' | 'expired' | 'cancelled', required
  - `type` 'health_insurance' | 'life_assurance', required
  - `provider` PolicyProviderResponse, required
    - `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, nullable: URL for the employer portal.
    - `employee_portal_url` string, nullable: URL for the employee portal (may include claims management).
    - `support_phone_number` string, nullable: Provider support phone number in E.164 format.
  - `plan` PolicyPlanResponse, required
    - `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` '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', required
    - `documents` PlanDocumentResponse[], required: List of plan documents (e.g., IPIDs, T&Cs).
      - `type` 'ipid' | 'table_of_cover' | 'waiting_periods' | 'hospital_list' | 'plan_summary' | 'terms_and_conditions' | 'other'
      - `title` string, required: Title of the document.
      - `link` string, required: Public URL to the document. This could be any format (PDF, HTML, etc.).
    - `coverage_options` PlanCoverageResponse[], 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.
      - `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.
      - `description` string, nullable: Full description of this coverage selection.
      - `scope` 'group_policy' | 'policy' | 'member', required
      - `input_type` 'single_select' | 'multi_select', required
      - `required` boolean, required: Whether a selection is mandatory.
      - `min_selections` integer, nullable: Minimum required selections (multi-select only).
      - `max_selections` integer, nullable: Maximum allowed selections (multi-select only).
      - `sort_order` integer, nullable: Display ordering hint.
      - `group_label` string, nullable: Optional grouping label for UI rendering. Indicates which coverage selections are best presented together from a UX standpoint.
      - `options` PlanCoverageOptionResponse[], required: Available options within this coverage selection.
        - `id` string, required: Unique identifier for this coverage option. Prefixed with `pco_`.
        - `name` string, required: Display name for this coverage option.
        - `description` string, nullable: Longer explanation of this coverage option.
        - `learn_more_url` string, nullable: Link to learn more about this coverage option.
        - `from_price` number, double, nullable: Lowest applicable monthly price for this coverage option.
        - `benefits` PlanCoverageOptionBenefitResponse[], nullable: Benefit items included with this coverage option.
          - `name` string, required: Benefit name.
          - `description` string, nullable: Benefit description.
        - `sub_options` PlanCoverageOptionResponse[], nullable: Nested sub-options available when this option is selected.
        - `eligibility_criteria` EmployerEligibilityCriterionResponse[], nullable: Eligibility criteria that must be met to select this coverage option.
          - `type` 'employees_count' | 'members_count' | 'industry_exclusions', required
          - `description` string, required: Human-readable description of the criterion.
          - `employees_count` EmployeesCountDetails
            - `min` integer, nullable: Minimum number of employees required.
            - `max` integer, nullable: Maximum number of employees allowed.
          - `members_count` MembersCountDetails
            - `min` integer, nullable: Minimum number of members required.
            - `max` integer, nullable: Maximum number of members allowed.
          - `industry_exclusions` IndustryExclusionsDetails
            - `excluded_industries` string[], required: List of excluded industries.
  - `health_insurance` HealthInsuranceGroupPolicyResponse
    - `group_policy_number` string, nullable: Provider-issued policy number. May be null if not yet issued.
    - `renewal` HealthInsurancePolicyRenewalResponse, required
      - `renewal_date` string, date, required: Renewal date.
      - `window_start_date` string, date, required: Renewal window start (inclusive).
      - `window_end_date` string, date, required: Renewal window end (inclusive).
      - `status` 'upcoming' | 'open' | 'renewed' | 'cancelled', required
      - `renewed_policy_id` string, nullable: Identifier of the renewed policy. This means existing policy will be replaced by the renewed policy on the renewal date.
    - `configuration` HealthInsuranceGroupPolicyConfigurationResponse, required
      - `cost_sharing` CostSharingConfigurationResponse, required
        - `type` 'member_count' | 'member_selection' | 'member_selection_percentage_based' | 'percentage' | 'policyholder_only' | 'family_type' | 'fixed_amount' | 'full_coverage' | 'pooled_member_count', required
        - `member_count` MemberCountCostSharingConfigurationResponse
          - `adults` integer, required: Number of additional adults covered, including partner/spouse.
          - `children` integer, required: Number of additional children covered.
        - `member_selection` MemberSelectionCostSharingConfigurationResponse
          - `partner` boolean, required: If a spouse/partner is covered.
          - `children` boolean, required: If children are covered.
        - `member_selection_percentage_based` 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.
        - `percentage` PercentageCostSharingConfigurationResponse
          - `percentage` integer, required: Employer coverage percentage: For 40% send 40. For 100% send 100.
        - `family_type` FamilyTypeCostSharingConfigurationResponse
          - `type` 'single' | 'couple' | 'single_with_children' | 'family', required
        - `fixed_amount` FixedAmountCostSharingConfigurationResponse
          - `monthly_amount` number, double, required: Monthly amount the employer covers, in the plan's currency. Must be positive.
        - `pooled_member_count` PooledMemberCountCostSharingConfigurationResponse
          - `dependents` integer, required: Number of dependents the employer covers in full, of any relationship: a spouse, partner or child each count as one. Must be zero or more.
      - `max_dependents` integer, nullable, required: The most dependents each policy under this group policy can cover at once, of any relationship: a spouse, partner or child each count as one. Null when there is no limit.
  - `life_assurance` LifeAssuranceGroupPolicyResponse
    - `group_policy_number` string, nullable: Provider-issued policy number. May be null if not yet issued.
    - `renewal` LifeAssurancePolicyRenewalResponse, required
      - `renewal_date` string, date, required: Renewal date.
      - `window_start_date` string, date, required: Renewal window start (inclusive).
      - `window_end_date` string, date, required: Renewal window end (inclusive).
      - `status` 'upcoming' | 'open' | 'renewed' | 'cancelled', required
      - `renewed_policy_id` string, nullable: Identifier of the renewed policy. This means existing policy will be replaced by the renewed policy on the renewal date.
    - `configuration` LifeAssuranceGroupPolicyConfigurationResponse, required
      - `cost_sharing` CostSharingConfigurationResponse, required
        - `type` 'member_count' | 'member_selection' | 'member_selection_percentage_based' | 'percentage' | 'policyholder_only' | 'family_type' | 'fixed_amount' | 'full_coverage' | 'pooled_member_count', required
        - `member_count` MemberCountCostSharingConfigurationResponse
          - `adults` integer, required: Number of additional adults covered, including partner/spouse.
          - `children` integer, required: Number of additional children covered.
        - `member_selection` MemberSelectionCostSharingConfigurationResponse
          - `partner` boolean, required: If a spouse/partner is covered.
          - `children` boolean, required: If children are covered.
        - `member_selection_percentage_based` 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.
        - `percentage` PercentageCostSharingConfigurationResponse
          - `percentage` integer, required: Employer coverage percentage: For 40% send 40. For 100% send 100.
        - `family_type` FamilyTypeCostSharingConfigurationResponse
          - `type` 'single' | 'couple' | 'single_with_children' | 'family', required
        - `fixed_amount` FixedAmountCostSharingConfigurationResponse
          - `monthly_amount` number, double, required: Monthly amount the employer covers, in the plan's currency. Must be positive.
        - `pooled_member_count` PooledMemberCountCostSharingConfigurationResponse
          - `dependents` integer, required: Number of dependents the employer covers in full, of any relationship: a spouse, partner or child each count as one. Must be zero or more.
  - `linked_group_policy_ids` 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` DisclosureResponse[], required: Disclosures associated with this group policy.
    - `category` 'regulatory' | 'provider' | 'intermediary', required
    - `type` 'intermediary_role' | 'intermediary_commission' | 'underwriter_disclaimer' | 'anti_selection_notice' | 'statement_of_needs' | 'product_information' | 'pre_existing_conditions' | 'statutory_warning' | 'privacy_policy' | 'terms_of_business', required
    - `title` string, required: The title of the disclosure statement.
    - `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` DisclosureLinkResponse[], required: The documents `text` names, one per placeholder it carries. Empty for a disclosure that is text only.
      - `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` 'intermediary_role' | 'intermediary_commission' | 'underwriter_disclaimer' | 'anti_selection_notice' | 'statement_of_needs' | 'product_information' | 'pre_existing_conditions' | 'statutory_warning' | 'privacy_policy' | 'terms_of_business', required
      - `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.
  - `object` string: The object type

## Other responses

- `404`: Not Found

## Changes

- **2026-10-26** `998f7cb004ab`: 1 warning
  - deleted the `header` request parameter `X-Platform-Id`
- …earlier changes not shown

[Operation history](https://skmtc.dev/kota/apis/kota-api/changes/group_policies/:group_policy_id/get.md)

---

[API](https://skmtc.dev/kota/apis/kota-api.md) - [All operations](https://skmtc.dev/kota/apis/kota-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kota/apis/kota-api/revisions/998f7cb004ab?raw)