generated: '2026-07-19'
method: derived
source: openapi/kota-openapi-original.json, https://docs.kota.io/key-concepts
description: Entity-relationship graph for the Kota API, derived from the OpenAPI schema graph and the
  published Key Concepts model.
hierarchy: Platform -> Employers -> (Employees, Groups) -> Group Policies -> Policies
entities:
- name: Platform
  description: A customer platform (payroll, HR or EOR) integrating Kota to offer benefits.
  api_resource: null
- name: Employer
  description: A legal entity in a specific country that provides policies to its employees. Transitions
    pending -> active during regulatory checks.
  api_resource: /employers
- name: Employee
  description: An individual who receives policies from their employer; may have dependants.
  api_resource: /employees
- name: AssociatedPerson
  description: A dependant or beneficiary (spouse, partner, child) attached to an employee.
  api_resource: /employees/{employee_id}/associated_persons
- name: Group
  description: Unified abstraction for managing policies of one or more benefit types; may be a bundle.
  api_resource: /groups
- name: GroupPolicy
  description: The collective benefit configuration established by an employer at group level with a provider.
  api_resource: /group_policies
- name: Policy
  description: The individual benefit issued to an employee who enrols, derived from the group policy.
  api_resource: /policies
- name: Plan
  description: A benefit plan/product available from a provider.
  api_resource: /plans
- name: GroupQuoteIntent
  description: Intent that requests quotes for a group from providers.
  api_resource: /group_quote_intents
- name: GroupPolicyIntent
  description: Intent that establishes the group policy once a quote is selected.
  api_resource: /group_policy_intents
- name: EnrolmentIntent
  description: Intent that guides an eligible employee through enrolment and issues a Policy.
  api_resource: /enrolment_intents
- name: DependentsManagementIntent
  description: Intent for adding, removing and confirming dependants during enrolment or the cooling-off
    period.
  api_resource: /dependents_management_intents
- name: PolicyAmendmentIntent
  description: Intent for amending an issued policy.
  api_resource: /policies/{policy_id}/policy_amendment_intents
- name: PolicyImportIntent
  description: Intent for migrating an existing policy into Kota.
  api_resource: /policy_import_intents
- name: Requirement
  description: A dynamic data requirement an intent returns that must be fulfilled before it can complete.
  api_resource: /requirements/{requirement_id}
- name: ContributionReport
  description: Periodic report of employee contributions for benefit premiums, with per-employee breakdowns.
  api_resource: /contribution_reports
- name: Event
  description: An immutable record of a state change on another API resource; retrievable for 30 days.
  api_resource: /events
- name: WebhookEndpoint
  description: A registered destination that receives Event objects.
  api_resource: /webhooks/endpoints
- name: EmbedSession
  description: Short-lived token authenticating an employer or employee Embed SDK UI.
  api_resource: /embed/sessions
- name: HostedSession
  description: One-off link into the Kota Hosted benefits experience.
  api_resource: /hosted/sessions
core_relationships:
- from: Platform
  to: Employer
  kind: has_many
  via: api key platform scope
- from: Employer
  to: Employee
  kind: has_many
  via: employer_id
- from: Employer
  to: Group
  kind: has_many
  via: employer_id
- from: Employee
  to: AssociatedPerson
  kind: has_many
  via: employee_id
- from: Group
  to: GroupPolicy
  kind: has_many
  via: group_id
- from: Group
  to: Employee
  kind: has_many
  via: group membership (AddEmployeeToGroup)
- from: GroupPolicy
  to: Policy
  kind: has_many
  via: group_policy_id
- from: Policy
  to: Employee
  kind: belongs_to
  via: employee_id
- from: Policy
  to: Plan
  kind: belongs_to
  via: plan_id
- from: EnrolmentIntent
  to: Policy
  kind: has_one
  via: intent completion
- from: GroupQuoteIntent
  to: GroupPolicyIntent
  kind: has_one
  via: quote selection
- from: GroupPolicyIntent
  to: GroupPolicy
  kind: has_one
  via: intent completion
- from: ContributionReport
  to: Employee
  kind: has_many
  via: employee_breakdowns
derived_id_relationships:
- from: AssociatedPersonEligibility
  to: AssociatedPerson
  kind: belongs_to
  via: associated_person_id
- from: AssociatedPersonEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: AssociatedPerson
  to: Platform
  kind: belongs_to
  via: platform_id
- from: AssociatedPerson
  to: Employee
  kind: belongs_to
  via: employee_id
- from: ContributionReportEmployeeBreakdown
  to: Employee
  kind: belongs_to
  via: employee_id
- from: ContributionReportEmployeeBreakdown
  to: ContributionReport
  kind: belongs_to
  via: contribution_report_id
- from: ContributionReportEmployeeBreakdown
  to: Employer
  kind: belongs_to
  via: employer_id
- from: ContributionReportEmployeeBreakdown
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: ContributionReportEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: ContributionReportEvent
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: ContributionReport
  to: Employer
  kind: belongs_to
  via: employer_id
- from: ContributionReport
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: DependentInfo
  to: AssociatedPerson
  kind: belongs_to
  via: associated_person_id
- from: DependentInfo
  to: Requirement
  kind: belongs_to
  via: requirement_id
- from: DependentsManagementIntentEvent
  to: DependentsManagementIntent
  kind: belongs_to
  via: dependents_management_intent_id
- from: DependentsManagementIntentEvent
  to: ParentIntent
  kind: belongs_to
  via: parent_intent_id
- from: DependentsManagementIntent
  to: ParentIntent
  kind: belongs_to
  via: parent_intent_id
- from: EmployeeEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: EmployeeHealthInsuranceOfferEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: EmployeeHealthInsuranceOfferEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: EmployeeHealthInsuranceOfferEvent
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: EmployeeHealthInsuranceOffer
  to: Employer
  kind: belongs_to
  via: employer_id
- from: EmployeeHealthInsuranceOffer
  to: Employee
  kind: belongs_to
  via: employee_id
- from: EmployeeHealthInsuranceOffer
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: EmployeeHealthInsurancePolicyEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: EmployeeHealthInsurancePolicyEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: EmployeeHealthInsurancePolicyEvent
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: EmployeeHealthInsurancePolicy
  to: Employer
  kind: belongs_to
  via: employer_id
- from: EmployeeHealthInsurancePolicy
  to: Employee
  kind: belongs_to
  via: employee_id
- from: EmployeeHealthInsurancePolicy
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: Employee
  to: Platform
  kind: belongs_to
  via: platform_id
- from: Employee
  to: Employer
  kind: belongs_to
  via: employer_id
- from: Employee
  to: ExternalCustomer
  kind: belongs_to
  via: external_customer_id
- from: Employee
  to: NationalTax
  kind: belongs_to
  via: national_tax_id
- from: EmployerHealthInsurancePolicy
  to: Employer
  kind: belongs_to
  via: employer_id
- from: EmployerHealthInsuranceQuoteEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: EmployerHealthInsuranceQuote
  to: Employer
  kind: belongs_to
  via: employer_id
- from: Employer
  to: Platform
  kind: belongs_to
  via: platform_id
- from: EnrolmentIntentDependent
  to: Intent
  kind: belongs_to
  via: intent_id
- from: EnrolmentIntentEvent
  to: EnrolmentIntent
  kind: belongs_to
  via: enrolment_intent_id
- from: EnrolmentIntentEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: EnrolmentIntentEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: EnrolmentIntentRequirement
  to: Object
  kind: belongs_to
  via: object_id
- from: EnrolmentIntent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: EnrolmentIntent
  to: Group
  kind: belongs_to
  via: group_id
- from: Event
  to: Platform
  kind: belongs_to
  via: platform_id
- from: GroupEmployeeEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupEmployeeEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: GroupEmployeeMoveScheduledEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: GroupEmployeeMoveScheduledEvent
  to: CurrentGroup
  kind: belongs_to
  via: current_group_id
- from: GroupEmployeeMoveScheduledEvent
  to: NewGroup
  kind: belongs_to
  via: new_group_id
- from: GroupEmployeeMovedEvent
  to: PreviousGroup
  kind: belongs_to
  via: previous_group_id
- from: GroupEmployeeMovedEvent
  to: NewGroup
  kind: belongs_to
  via: new_group_id
- from: GroupEmployeeMovedEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: GroupEmployeeRemovedEvent
  to: Platform
  kind: belongs_to
  via: platform_id
- from: GroupEmployeeRemovedEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: GroupEmployeeRemovedEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupEmployeeRemovedEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: GroupEmployee
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: GroupPolicyEvent
  to: GroupPolicy
  kind: belongs_to
  via: group_policy_id
- from: GroupPolicyEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupPolicyEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: GroupPolicyIntentEvent
  to: GroupPolicyIntent
  kind: belongs_to
  via: group_policy_intent_id
- from: GroupPolicyIntentEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupPolicyIntentEvent
  to: Plan
  kind: belongs_to
  via: plan_id
- from: GroupPolicyIntentRequirement
  to: Object
  kind: belongs_to
  via: object_id
- from: GroupPolicyIntent
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupPolicyIntent
  to: Plan
  kind: belongs_to
  via: plan_id
- from: GroupPolicyIntent
  to: QuoteIntent
  kind: belongs_to
  via: quote_intent_id
- from: GroupPolicy
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupPolicy
  to: Employer
  kind: belongs_to
  via: employer_id
- from: GroupQuoteIntentEvent
  to: GroupQuoteIntent
  kind: belongs_to
  via: group_quote_intent_id
- from: GroupQuoteIntentEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupQuoteIntentEvent
  to: Plan
  kind: belongs_to
  via: plan_id
- from: GroupQuoteIntentRequirement
  to: Object
  kind: belongs_to
  via: object_id
- from: GroupQuoteIntent
  to: Group
  kind: belongs_to
  via: group_id
- from: GroupQuoteIntent
  to: Plan
  kind: belongs_to
  via: plan_id
- from: Group
  to: Employer
  kind: belongs_to
  via: employer_id
- from: HealthInsuranceCoverageLevel
  to: Plan
  kind: belongs_to
  via: plan_id
- from: HealthInsurancePolicyRenewal
  to: RenewedPolicy
  kind: belongs_to
  via: renewed_policy_id
- from: PlanCoverageOptionSelection
  to: Configuration
  kind: belongs_to
  via: configuration_id
- from: PolicyAmendmentDependents
  to: DependentsManagementIntent
  kind: belongs_to
  via: dependents_management_intent_id
- from: PolicyAmendmentIntentEvent
  to: PolicyAmendmentIntent
  kind: belongs_to
  via: policy_amendment_intent_id
- from: PolicyAmendmentIntentEvent
  to: Policy
  kind: belongs_to
  via: policy_id
- from: PolicyAmendmentIntentEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: PolicyAmendmentIntentEvent
  to: Employer
  kind: belongs_to
  via: employer_id
- from: PolicyAmendmentIntent
  to: Policy
  kind: belongs_to
  via: policy_id
- from: PolicyEvent
  to: Policy
  kind: belongs_to
  via: policy_id
- from: PolicyEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: PolicyEvent
  to: GroupPolicy
  kind: belongs_to
  via: group_policy_id
- from: PolicyEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: PolicyImportIntentAssociatedPerson
  to: AssociatedPerson
  kind: belongs_to
  via: associated_person_id
- from: PolicyImportIntentEvent
  to: PolicyImportIntent
  kind: belongs_to
  via: policy_import_intent_id
- from: PolicyImportIntentEvent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: PolicyImportIntentEvent
  to: Group
  kind: belongs_to
  via: group_id
- from: PolicyImportIntentEvent
  to: Policy
  kind: belongs_to
  via: policy_id
- from: PolicyImportIntent
  to: Employee
  kind: belongs_to
  via: employee_id
- from: PolicyImportIntent
  to: Group
  kind: belongs_to
  via: group_id
- from: PolicyMember
  to: AssociatedPerson
  kind: belongs_to
  via: associated_person_id
- from: Policy
  to: Employee
  kind: belongs_to
  via: employee_id
- from: Policy
  to: GroupPolicy
  kind: belongs_to
  via: group_policy_id
- from: Policy
  to: Group
  kind: belongs_to
  via: group_id
- from: ReplayDelivery
  to: Delivery
  kind: belongs_to
  via: delivery_id
- from: ReplayEvent
  to: Event
  kind: belongs_to
  via: event_id
- from: ScheduledGroupTransition
  to: NewGroup
  kind: belongs_to
  via: new_group_id
- from: SelectedOption
  to: Option
  kind: belongs_to
  via: option_id
notes: 'Kota models every mutating workflow as an intent: create -> fulfil data requirements -> complete,
  which then produces the result object (Quote, Group Policy, Policy).'