> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/api-reference/enrolment-intents/retrieve-enrolment-intent/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server. # Retrieve an enrolment intent GET https://test.api.kota.io/enrolment_intents/{enrolment_intent_id} Retrieves an `enrolment_intent` object. Reference: https://docs.kota.io/api-reference/enrolment-intents/retrieve-enrolment-intent ## 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 - `enrolment_intent_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 enrolment intent. Prefixed with `ei_`. - `employee_id` (string, required) — Identifier for the employee associated with this enrolment intent. Prefixed with `ee_`. - `group_id` (string, required) — Identifier for the group associated with this enrolment intent. Prefixed with `gr_`. - `status` (enum, required) — Current status of the enrolment intent. - Allowed values: `processing`, `scheduled`, `action_required`, `coverage_options_required`, `pending_confirmation`, `enrolling`, `enrolled`, `not_undertaken`, `ineligible`, `rejected` - `force_confirmation` (boolean, required) — If set to true, the system will always force the `PendingConfirmation` state before enrolling the employee, even if no action is required. This can be useful in scenarios where you want to ensure that the employee explicitly confirms their enrolment, regardless of their eligibility or any other factors. Defaults to false. - `policy_enrolments` (list of EnrolmentIntentPolicyEnrolmentResponse, required) — Policy enrolment information - `disclosures` (list of DisclosureResponse, required) — Disclosures associated with this intent. - `object` (string, optional) — Object type identifier. - `ineligibility_reason` (EnrolmentIntentInelgibilityReason, optional) — If the enrolment intent status is `ineligible`, this field provides details about the reason for employees ineligibility. - `policy_configuration` (PolicyConfigurationResponse, optional) — Policy configuration associated with this enrolment intent. - `action_required` (EnrolmentIntentActionRequiredResponse, optional) — If the enrolment intent status is `action_required`, this field provides details about the action that needs to be taken to proceed with the enrolment. - `pending_confirmation` (EnrolmentIntentPendingConfirmationResponse, optional) — If the enrolment intent status is `pending_confirmation`, this field provides details about the pending confirmation state. ## 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 ### EnrolmentIntentPolicyEnrolmentResponse - `type` (enum, required) — Type of policy to be created as part of this enrolment intent. - Allowed values: `health_insurance`, `life_assurance` - `estimated_effective_from` (date, required) — Estimated date when the policy of this type is expected to become effective in ISO 8601 (YYYY-MM-DD). - `provider` (PolicyProviderResponse, required) — Provider information for this policy (from group policy). - `plan` (PolicyPlanResponse, required) — Plan information for this policy (from group policy). - `health_insurance` (HealthInsuranceEnrolmentIntentResponse, optional) — Health insurance intent information (always present when type=health_insurance). - `id` (string, optional, nullable) — Unique identifier for the policy created as part of this enrolment intent. Prefixed with `p_`. Only populated once the policy has been created. ### 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. ### EnrolmentIntentInelgibilityReason - `code` (enum, required) — Code representing the reason for ineligibility. This can be used to programmatically handle different ineligibility scenarios. As these amount of codes could increase with new providers we strongly suggest to use the fallback public message for displaying to end users. - Allowed values: `employee_restricted`, `employee_under_minimum_age`, `employee_above_maximum_age`, `employee_not_active`, `employment_not_started`, `unknown` - `reason` (string, required) — A reason that can be displayed to the end user explaining why the enrolment intent is ineligible. ### PolicyConfigurationResponse - `desired_policy_start_date` (date, optional, nullable) — Desired policy start date, not guaranteed to be honoured by the provider. - `enrolment_date` (date, optional, nullable) — The date on which the employee has agreed to enrol into a the group policy. This date may be used by some providers to determine policy start date. ### EnrolmentIntentActionRequiredResponse - `code` (enum, required) — The action code indicating what action is required. - Allowed values: `provide_dependant_information`, `provide_beneficiary_information`, `provide_missing_information` - `reason` (string, required) — Brief reason for the required action. - `reason_description` (string, required) — Detailed description of the required action. - `due_by` (datetime, required) — The deadline by which the action must be completed. The day is included (i.e. the action can be completed any time during this day in the user's local time). ### EnrolmentIntentPendingConfirmationResponse - `due_by` (datetime, required) — The deadline by which the confirmation must be completed. - `code` (enum, required) — The code for the confirmation that needs to be taken. - Allowed values: `confirm_enrolment` - `reason` (string, required) — A reason for the confirmation action that needs to be taken. - `reason_description` (string, required) — A reason description explaining the confirmation action that needs to be taken. - `associated_persons` (EnrolmentIntentAssociatedPersonResponse, optional) — Information about associated persons related to this enrolment. Used to manage dependents. ### 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. ### HealthInsuranceEnrolmentIntentResponse - `configuration` (HealthInsurancePolicyConfigurationResponse, required) — How benefit costs will be shared between employer and employee. - `coverage_options` (list of PlanCoverageResponse, optional, nullable) — Available plan coverage options at the policy scope. Only present when the plan has policy-scoped coverage configurations. - `coverage_selections` (list of PlanCoverageOptionSelectionResponse, optional, nullable) — Current coverage option selections. Populated when selections have been submitted. ### 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. ### EnrolmentIntentAssociatedPersonResponse - `optional` (boolean, required) — Indicates whether providing information for the related type is optional. - `type` (enum, required) — The type of associated person. - Allowed values: `dependents` - `dependent` (EnrolmentIntentDependentResponse, required) — Dependents-specific information if type is 'dependents'. ### 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. ### HealthInsurancePolicyConfigurationResponse - `cost_sharing` (CostSharingConfigurationResponse, required) — Defines how the policy total cost is shared between employer and employee. ### PlanCoverageOptionSelectionResponse - `configuration_id` (string, required) — Configuration ID (prefixed with `pc_`). - `options` (list of SelectedOptionResponse, required) — Selected options. ### EnrolmentIntentDependentResponse - `intent_id` (string, required) — Unique identifier for the dependents management intent. Prefixed with `dmi_`. - `status` (enum, required) — Current status of the dependent. - Allowed values: `processing`, `confirmed` ### 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. ### SelectedOptionResponse - `option_id` (string, required) — Option ID (prefixed with `pco_`). - `sub_options` (list of SelectedOptionResponse, optional, nullable) — Selected sub-options, if applicable. ### 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": "ei_3b1333d87d9d4fd6ad83ba7f6b0e951a", "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a", "group_id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a", "status": "processing", "force_confirmation": true, "policy_enrolments": [ { "type": "health_insurance", "estimated_effective_from": "2024-12-01", "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 }, "health_insurance": null, "id": "p_3b1333d87d9d4fd6ad83ba7f6b0e951a" } ], "disclosures": [ { "category": "regulatory", "type": "intermediary_role", "text": "string", "links": [ { "token": "string", "type": "intermediary_role", "label": "string", "url": "string", "version": "string" } ] } ], "object": "string", "ineligibility_reason": null, "policy_configuration": null, "action_required": null, "pending_confirmation": null } ``` **SDK Code** ```python import requests url = "https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://test.api.kota.io/enrolment_intents/ei_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/enrolment_intents/ei_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/enrolment_intents/ei_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/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://test.api.kota.io/enrolment_intents/ei_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/enrolment_intents/ei_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() ```