Kota Group Policy Intents API

openapi: 3.1.0
info:
  title: API Reference Associated Persons Group Policy Intents API
  version: 1.0.0
servers:
- url: https://test.api.kota.io
  description: test
- url: https://api.kota.io
  description: production
tags:
- name: Group Policy Intents
paths:
  /group_policy_intents:
    post:
      tags:
      - Group Policy Intents
      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.
      operationId: CreateGroupPolicyIntent
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateGroupPolicyIntentRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags:
      - 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.
      operationId: ListGroupPolicyIntents
      parameters:
      - name: group_id
        in: query
        description: Filter by group ID
        schema:
          pattern: gr_.+
          type: string
          description: Filter by group ID
          example: gr_3b1333d87d9d4fd6ad83ba7f6b0e951a
      - name: plan_id
        in: query
        description: Filter by plan ID
        schema:
          pattern: pl_.+
          type: string
          description: Filter by plan ID
          example: pl_3b1333d87d9d4fd6ad83ba7f6b0e951a
      - 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`.'
        schema:
          type: string
      - name: page
        in: query
        description: The page of results to return. Defaults to 1 if not provided.
        schema:
          type: integer
          description: The page of results to return. Defaults to 1 if not provided.
          format: int32
      - name: page_size
        in: query
        description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
        schema:
          type: integer
          description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentResponsePagedList'
  /group_policy_intents/{group_policy_intent_id}:
    get:
      tags:
      - Group Policy Intents
      summary: Retrieve a group policy intent
      description: Retrieves a `group_policy_intent` object.
      operationId: RetrieveGroupPolicyIntent
      parameters:
      - name: group_policy_intent_id
        in: path
        required: true
        schema:
          pattern: gpi_.+
          type: string
          example: gpi_3b1333d87d9d4fd6ad83ba7f6b0e951a
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentResponse'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /group_policy_intents/{group_policy_intent_id}/requirements:
    get:
      tags:
      - Group Policy Intents
      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.
      operationId: ListGroupPolicyIntentRequirements
      parameters:
      - name: group_policy_intent_id
        in: path
        required: true
        schema:
          pattern: gpi_.+
          type: string
          example: gpi_3b1333d87d9d4fd6ad83ba7f6b0e951a
      - name: object_type
        in: query
        description: Filter by object type (employee or employer)
        schema:
          allOf:
          - $ref: '#/components/schemas/RequirementObjectTypeEnumParameter'
          description: Filter by object type (employee or employer)
      - name: object_id
        in: query
        description: Filter by object ID (employee ID or employer ID)
        schema:
          type: string
          description: Filter by object ID (employee ID or employer ID)
      - name: page
        in: query
        description: The page of results to return. Defaults to 1 if not provided.
        schema:
          type: integer
          description: The page of results to return. Defaults to 1 if not provided.
          format: int32
      - name: page_size
        in: query
        description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
        schema:
          type: integer
          description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPolicyIntentRequirementResponsePagedList'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    RequirementType:
      enum:
      - group_quote_intent
      - group_policy_intent
      - dependent_management_intent
      - policy_amendment_intent
      - enrolment_intent
      type: string
    HealthInsuranceFamilyTypeCostSharingConfigurationResponse:
      required:
      - type
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/HealthInsuranceFamilyCostSharingType'
          description: Employer coverage family type
      additionalProperties: false
    GroupPolicyIntentStatus:
      enum:
      - processing
      - action_required
      - pending_provider_approval
      - policy_created
      - expired
      - provider_rejected
      - manual_renewal_gathering_required
      type: string
    ConsentType:
      enum:
      - terms_of_business
      - privacy_policy
      type: string
    HealthInsuranceMemberSelectionCostSharingConfigurationResponse:
      required:
      - children
      - partner
      type: object
      properties:
        partner:
          type: boolean
          description: If a spouse/partner is covered.
          example: true
        children:
          type: boolean
          description: If children are covered.
          example: true
      additionalProperties: false
    GroupPolicyIntentResponse:
      required:
      - disclosures
      - group_id
      - id
      - plan_id
      - quote_intent_id
      - status
      type: object
      properties:
        id:
          pattern: gpi_.+
          type: string
          description: Unique identifier for the group policy intent
          example: gpi_3b1333d87d9d4fd6ad83ba7f6b0e951a
        group_id:
          pattern: gr_.+
          type: string
          description: Unique identifier for the group
          example: gr_3b1333d87d9d4fd6ad83ba7f6b0e951a
        plan_id:
          pattern: pl_.+
          type: string
          description: Unique identifier for the plan
          example: pl_3b1333d87d9d4fd6ad83ba7f6b0e951a
        quote_intent_id:
          pattern: gqi_.+
          type: string
          description: Unique identifier for the group quote intent this policy intent was created from
          example: gqi_3b1333d87d9d4fd6ad83ba7f6b0e951a
        status:
          allOf:
          - $ref: '#/components/schemas/GroupPolicyIntentStatus'
          description: Current status of the group policy intent
        due_date:
          type:
          - 'null'
          - string
          description: Due date for the policy intent
          format: date-time
          example: '2024-12-01T00:00:00Z'
        cost_sharing:
          type: 'null'
          allOf:
          - $ref: '#/components/schemas/HealthInsuranceCostSharingConfigurationResponse'
          description: Cost sharing configuration for the policy intent
        action_required:
          type: 'null'
          allOf:
          - $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
          readOnly: true
      additionalProperties: false
    RequirementObjectType:
      enum:
      - employee
      - employer
      - associated_person
      type: string
    HealthInsuranceCostSharingType:
      enum:
      - member_count
      - member_selection
      - percentage
      - policyholder_only
      - family_type
      type: string
      x-fern-enum:
        member_count:
          description: The number of additional adults and children to cover is specified.
        member_selection:
          description: Dependent categories to cover are selected (partner and/or children).
        percentage:
          description: A percentage of the total premium is covered.
        policyholder_only:
          description: Only the policyholder is covered.
        family_type:
          description: Coverage is based on a predefined family tier (e.g. Single, Couple, Family).
    CreateGroupPolicyIntentRequest:
      required:
      - quote_intent_id
      type: object
      properties:
        quote_intent_id:
          pattern: gqi_.+
          type: string
          description: Unique identifier for the group quote intent to create a policy intent from
          example: gqi_3b1333d87d9d4fd6ad83ba7f6b0e951a
        cost_sharing:
          type: 'null'
          allOf:
          - $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:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/ConsentApprovalInput'
          description: Consent approvals to record at the time of intent creation
      additionalProperties: false
    GroupPolicyIntentResponsePagedList:
      required:
      - items
      - page
      - page_size
      - total_count
      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
          format: int32
          example: 123
        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
          format: int32
          example: 123
        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.
          format: int32
          example: 123
        has_next_page:
          type: boolean
          description: Whether there are more pages available after this page
          readOnly: true
          example: true
        has_previous_page:
          type: boolean
          description: Whether there are more pages available before this page
          readOnly: true
          example: true
      additionalProperties: false
    DisclosureType:
      enum:
      - intermediary_role
      - intermediary_commission
      - underwriter_disclaimer
      - anti_selection_notice
      - statement_of_needs
      - product_information
      - pre_existing_conditions
      - statutory_warning
      type: string
    HealthInsurancePercentageCostSharingConfigurationResponse:
      required:
      - percentage
      type: object
      properties:
        percentage:
          type: integer
          description: "Employer coverage percentage:\n For 40% send 40.\n For 100% send 100."
          format: int32
          example: 123
      additionalProperties: false
    HealthInsuranceMemberCountCostSharingConfigurationResponse:
      required:
      - adults
      - children
      type: object
      properties:
        adults:
          type: integer
          description: Number of additional adults covered, including partner/spouse.
          format: int32
          example: 123
        children:
          type: integer
          description: Number of additional children covered.
          format: int32
          example: 123
      additionalProperties: false
    GroupPolicyIntentRequirementResponse:
      required:
      - id
      - is_fulfilled
      - object_id
      - object_type
      - requirement_type
      type: object
      properties:
        id:
          pattern: ar_.+
          type: string
          description: Unique identifier for the requirement
          example: ar_3b1333d87d9d4fd6ad83ba7f6b0e951a
        object_type:
          allOf:
          - $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
          example: true
        requirement_type:
          allOf:
          - $ref: '#/components/schemas/RequirementType'
          description: Type of requirement
        object:
          type: string
          description: Object type identifier
          readOnly: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - 'null'
          - string
        title:
          type:
          - 'null'
          - string
        status:
          type:
          - 'null'
          - integer
          format: int32
        detail:
          type:
          - 'null'
          - string
        instance:
          type:
          - 'null'
          - string
      additionalProperties: {}
    IntentActionType:
      enum:
      - provide_dependant_information
      - provide_beneficiary_information
      - provide_missing_information
      type: string
    HealthInsuranceCostSharingConfigurationResponse:
      required:
      - type
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/HealthInsuranceCostSharingType'
          description: Cost sharing type. Determines which sub-object is populated.
        member_count:
          type: 'null'
          allOf:
          - $ref: '#/components/schemas/HealthInsuranceMemberCountCostSharingConfigurationResponse'
          description: Numbers of additional members covered by the employer.
        member_selection:
          type: 'null'
          allOf:
          - $ref: '#/components/schemas/HealthInsuranceMemberSelectionCostSharingConfigurationResponse'
          description: Whether specific member types are covered by the employer.
        percentage:
          type: 'null'
          allOf:
          - $ref: '#/components/schemas/HealthInsurancePercentageCostSharingConfigurationResponse'
          description: Percentage of the premium the employer covers.
        family_type:
          type: 'null'
          allOf:
          - $ref: '#/components/schemas/HealthInsuranceFamilyTypeCostSharingConfigurationResponse'
          description: Type of the family covered by the employer.
      additionalProperties: false
    RequirementObjectTypeEnumParameter:
      type: object
      properties:
        value:
          allOf:
          - $ref: '#/components/schemas/RequirementObjectType'
      additionalProperties: false
    DisclosureResponse:
      required:
      - category
      - text
      - type
      type: object
      properties:
        category:
          allOf:
          - $ref: '#/components/schemas/DisclosureCategory'
          description: The category of the disclosure.
        type:
          allOf:
          - $ref: '#/components/schemas/DisclosureType'
          description: The specific type of disclosure within its category.
        text:
          type: string
          description: The disclosure statement text.
      additionalProperties: false
    GroupPolicyIntentRequirementResponsePagedList:
      required:
      - items
      - page
      - page_size
      - total_count
      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
          format: int32
          example: 123
        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
          format: int32
          example: 123
        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.
          format: int32
          example: 123
        has_next_page:
          type: boolean
          description: Whether there are more pages available after this page
          readOnly: true
          example: true
        has_previous_page:
          type: boolean
          description: Whether there are more pages available before this page
          readOnly: true
          example: true
      additionalProperties: false
    DisclosureCategory:
      enum:
      - regulatory
      - provider
      - intermediary
      type: string
    ConsentApprovalInput:
      required:
      - ip
      - type
      - user_id
      - version
      type: object
      properties:
        type:
          allOf:
          - $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
      additionalProperties: false
    GroupPolicyIntentActionRequiredResponse:
      required:
      - code
      - due_by
      - reason
      - reason_description
      type: object
      properties:
        code:
          allOf:
          - $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
          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).
          format: date-time
          example: '2024-12-01T00:00:00Z'
      additionalProperties: false
    HealthInsuranceFamilyCostSharingType:
      enum:
      - single
      - couple
      - single_with_children
      - family
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization header using the Bearer scheme