Kota groupPolicyIntents API

openapi: 3.1.0
info:
  title: API Reference Associated Persons groupPolicyIntents API
  version: 1.0.0
servers:
- url: https://test.api.kota.io
  description: test
- url: https://api.kota.io
  description: production
tags:
- name: groupPolicyIntents
paths:
  /group_policy_intents:
    get:
      operationId: list-group-policy-intents
      summary: List group policy intents
      description: Returns a paginated list of `group_policy_intent`'s. The results are returned sorted by creation date, with the most recent appearing first.
      tags:
      - groupPolicyIntents
      parameters:
      - name: group_id
        in: query
        description: Filter by group ID
        required: false
        schema:
          type: string
      - name: plan_id
        in: query
        description: Filter by plan ID
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: 'Multiple values can be provided by separating them with a comma. Allowed values are: `processing`, `action_required`, `pending_provider_approval`, `policy_created`, `expired`, `provider_rejected`, `manual_renewal_gathering_required`.'
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: The page of results to return. Defaults to 1 if not provided.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentResponsePagedList'
    post:
      operationId: create-group-policy-intent
      summary: Create a group policy intent
      description: Creates a `group_policy_intent` from a `group_quote_intent` that has a quote available. The intent coordinates the policy setup workflow including requirements collection and policy creation.
      tags:
      - groupPolicyIntents
      parameters:
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupPolicyIntentRequest'
  /group_policy_intents/{group_policy_intent_id}:
    get:
      operationId: retrieve-group-policy-intent
      summary: Retrieve a group policy intent
      description: Retrieves a `group_policy_intent` object.
      tags:
      - groupPolicyIntents
      parameters:
      - name: group_policy_intent_id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /group_policy_intents/{group_policy_intent_id}/requirements:
    get:
      operationId: list-group-policy-intent-requirements
      summary: List requirements for a group policy intent
      description: Returns a paginated list of adaptive requirements for a `group_policy_intent`. Requirements must be fulfilled before policy setup can proceed.
      tags:
      - groupPolicyIntents
      parameters:
      - name: group_policy_intent_id
        in: path
        required: true
        schema:
          type: string
      - name: object_type
        in: query
        description: Filter by object type (employee or employer)
        required: false
        schema:
          $ref: '#/components/schemas/RequirementObjectTypeEnumParameter'
      - name: object_id
        in: query
        description: Filter by object ID (employee ID or employer ID)
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: The page of results to return. Defaults to 1 if not provided.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentRequirementResponsePagedList'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    RequirementType:
      type: string
      enum:
      - group_quote_intent
      - group_policy_intent
      - dependent_management_intent
      - policy_amendment_intent
      - enrolment_intent
      title: RequirementType
    HealthInsuranceFamilyTypeCostSharingConfigurationResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/HealthInsuranceFamilyCostSharingType'
          description: Employer coverage family type
      required:
      - type
      title: HealthInsuranceFamilyTypeCostSharingConfigurationResponse
    GroupPolicyIntentStatus:
      type: string
      enum:
      - processing
      - action_required
      - pending_provider_approval
      - policy_created
      - expired
      - provider_rejected
      - manual_renewal_gathering_required
      title: GroupPolicyIntentStatus
    ConsentType:
      type: string
      enum:
      - terms_of_business
      - privacy_policy
      title: ConsentType
    HealthInsuranceMemberSelectionCostSharingConfigurationResponse:
      type: object
      properties:
        partner:
          type: boolean
          description: If a spouse/partner is covered.
        children:
          type: boolean
          description: If children are covered.
      required:
      - partner
      - children
      title: HealthInsuranceMemberSelectionCostSharingConfigurationResponse
    GroupPolicyIntentResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the group policy intent
        group_id:
          type: string
          description: Unique identifier for the group
        plan_id:
          type: string
          description: Unique identifier for the plan
        quote_intent_id:
          type: string
          description: Unique identifier for the group quote intent this policy intent was created from
        status:
          $ref: '#/components/schemas/GroupPolicyIntentStatus'
          description: Current status of the group policy intent
        due_date:
          type:
          - string
          - 'null'
          format: date-time
          description: Due date for the policy intent
        cost_sharing:
          $ref: '#/components/schemas/HealthInsuranceCostSharingConfigurationResponse'
          description: Cost sharing configuration for the policy intent
        action_required:
          $ref: '#/components/schemas/GroupPolicyIntentActionRequiredResponse'
          description: Details of the required action when the intent is in ActionRequired status.
        disclosures:
          type: array
          items:
            $ref: '#/components/schemas/DisclosureResponse'
          description: Disclosures associated with this intent.
        object:
          type: string
          description: Object type identifier
      required:
      - id
      - group_id
      - plan_id
      - quote_intent_id
      - status
      - disclosures
      title: GroupPolicyIntentResponse
    RequirementObjectType:
      type: string
      enum:
      - employee
      - employer
      - associated_person
      title: RequirementObjectType
    HealthInsuranceCostSharingType:
      type: string
      enum:
      - member_count
      - member_selection
      - percentage
      - policyholder_only
      - family_type
      title: HealthInsuranceCostSharingType
    CreateGroupPolicyIntentRequest:
      type: object
      properties:
        quote_intent_id:
          type: string
          description: Unique identifier for the group quote intent to create a policy intent from
        cost_sharing:
          $ref: '#/components/schemas/HealthInsuranceCostSharingConfigurationResponse'
          description: Cost sharing configuration override for the setup. If not provided, falls back to the quote intent's cost sharing.
        consent_approvals:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ConsentApprovalInput'
          description: Consent approvals to record at the time of intent creation
      required:
      - quote_intent_id
      title: CreateGroupPolicyIntentRequest
    GroupPolicyIntentResponsePagedList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/GroupPolicyIntentResponse'
          description: A paginated array containing the response elements
        page:
          type: integer
          description: The current page of the results
        page_size:
          type: integer
          description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
        total_count:
          type: integer
          description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
        has_next_page:
          type: boolean
          description: Whether there are more pages available after this page
        has_previous_page:
          type: boolean
          description: Whether there are more pages available before this page
      required:
      - items
      - page
      - page_size
      - total_count
      title: GroupPolicyIntentResponsePagedList
    DisclosureType:
      type: string
      enum:
      - intermediary_role
      - intermediary_commission
      - underwriter_disclaimer
      - anti_selection_notice
      - statement_of_needs
      - product_information
      - pre_existing_conditions
      - statutory_warning
      title: DisclosureType
    HealthInsurancePercentageCostSharingConfigurationResponse:
      type: object
      properties:
        percentage:
          type: integer
          description: "Employer coverage percentage:\n For 40% send 40.\n For 100% send 100."
      required:
      - percentage
      title: HealthInsurancePercentageCostSharingConfigurationResponse
    HealthInsuranceMemberCountCostSharingConfigurationResponse:
      type: object
      properties:
        adults:
          type: integer
          description: Number of additional adults covered, including partner/spouse.
        children:
          type: integer
          description: Number of additional children covered.
      required:
      - adults
      - children
      title: HealthInsuranceMemberCountCostSharingConfigurationResponse
    GroupPolicyIntentRequirementResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the requirement
        object_type:
          $ref: '#/components/schemas/RequirementObjectType'
          description: Type of object this requirement is for (employee or employer)
        object_id:
          type: string
          description: Identifier of the object (employee ID or employer ID)
        is_fulfilled:
          type: boolean
          description: Whether the requirement has been fulfilled
        requirement_type:
          $ref: '#/components/schemas/RequirementType'
          description: Type of requirement
        object:
          type: string
          description: Object type identifier
      required:
      - id
      - object_type
      - object_id
      - is_fulfilled
      - requirement_type
      title: GroupPolicyIntentRequirementResponse
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      title: ProblemDetails
    IntentActionType:
      type: string
      enum:
      - provide_dependant_information
      - provide_beneficiary_information
      - provide_missing_information
      title: IntentActionType
    HealthInsuranceCostSharingConfigurationResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/HealthInsuranceCostSharingType'
          description: Cost sharing type. Determines which sub-object is populated.
        member_count:
          $ref: '#/components/schemas/HealthInsuranceMemberCountCostSharingConfigurationResponse'
          description: Numbers of additional members covered by the employer.
        member_selection:
          $ref: '#/components/schemas/HealthInsuranceMemberSelectionCostSharingConfigurationResponse'
          description: Whether specific member types are covered by the employer.
        percentage:
          $ref: '#/components/schemas/HealthInsurancePercentageCostSharingConfigurationResponse'
          description: Percentage of the premium the employer covers.
        family_type:
          $ref: '#/components/schemas/HealthInsuranceFamilyTypeCostSharingConfigurationResponse'
          description: Type of the family covered by the employer.
      required:
      - type
      title: HealthInsuranceCostSharingConfigurationResponse
    RequirementObjectTypeEnumParameter:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/RequirementObjectType'
      title: RequirementObjectTypeEnumParameter
    DisclosureResponse:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/DisclosureCategory'
          description: The category of the disclosure.
        type:
          $ref: '#/components/schemas/DisclosureType'
          description: The specific type of disclosure within its category.
        text:
          type: string
          description: The disclosure statement text.
      required:
      - category
      - type
      - text
      title: DisclosureResponse
    GroupPolicyIntentRequirementResponsePagedList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/GroupPolicyIntentRequirementResponse'
          description: A paginated array containing the response elements
        page:
          type: integer
          description: The current page of the results
        page_size:
          type: integer
          description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
        total_count:
          type: integer
          description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
        has_next_page:
          type: boolean
          description: Whether there are more pages available after this page
        has_previous_page:
          type: boolean
          description: Whether there are more pages available before this page
      required:
      - items
      - page
      - page_size
      - total_count
      title: GroupPolicyIntentRequirementResponsePagedList
    DisclosureCategory:
      type: string
      enum:
      - regulatory
      - provider
      - intermediary
      title: DisclosureCategory
    ConsentApprovalInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ConsentType'
          description: Type of consent being approved
        ip:
          type: string
          description: IP address of the user approving
        version:
          type: string
          description: Version of the consent document being approved
        user_id:
          type: string
          description: User ID approving the consent
      required:
      - type
      - ip
      - version
      - user_id
      title: ConsentApprovalInput
    GroupPolicyIntentActionRequiredResponse:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/IntentActionType'
          description: The action code indicating what action is required.
        reason:
          type: string
          description: Brief reason for the required action.
        reason_description:
          type: string
          description: Detailed description of the required action.
        due_by:
          type: string
          format: date-time
          description: 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).
      required:
      - code
      - reason
      - reason_description
      - due_by
      title: GroupPolicyIntentActionRequiredResponse
    HealthInsuranceFamilyCostSharingType:
      type: string
      enum:
      - single
      - couple
      - single_with_children
      - family
      title: HealthInsuranceFamilyCostSharingType
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization header using the Bearer scheme