PlanSource Coverage API

openapi: 3.2.0
info:
  title: Plansource Admin Coverage API
  description: An integration API for Plansource data for administration functions
  contact:
    name: Plansource API team
    email: api-team@plansource.com
  license:
    name: B) 2017 Plansource.  All rights reserved.
  version: 2.0.0
servers:
- url: https://api.plansource.com/admin/v2
security:
- clientSecretJwt:
  - admin_api_v2
- authString: []
  signature: []
tags:
- name: Coverage
  description: Coverages, coverage lines, and dependent coverages.
paths:
  /coverage:
    post:
      tags:
      - Coverage
      description: Create coverage
      parameters:
      - name: plan_year
        in: query
        description: Plan year
        required: false
        schema:
          type: string
          enum:
          - previous
          - current
          - next
      - name: recalculate
        in: query
        description: Perform a recalculate of the coverage
        required: false
        schema:
          type: boolean
      - name: validate_volume
        in: query
        description: Perform the validation of the coverage
        required: false
        schema:
          type: boolean
      - name: recalculate_volume
        in: query
        description: Perform a volume recalculate of the coverage
        required: false
        schema:
          type: boolean
      - name: set_original_effective_date
        in: query
        description: Allow the setting of the original effective date
        required: false
        schema:
          type: string
          format: date
      - name: set_change_effective_date
        in: query
        description: Allow the setting of the change effective date
        required: false
        schema:
          type: string
          format: date
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCoverageModel'
        required: true
      responses:
        '200':
          description: Create coverage response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoveragesResponseOK'
              examples:
                response: {}
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Not enough or too many segments
                    data: []
        '401':
          description: Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 401
                      message: Signature has expired
                      error_code: invalid_token
                    data: []
        '403':
          description: Access error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 403
                      message: Forbidden
                    data: []
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 404
                      message: Requested route 'coverag' not found
                      error_code: route_not_found
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoLinks500Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 500
                      message: Internal error
                    data: []
  /coverage/meta:
    get:
      tags:
      - Coverage
      description: Retrieve meta data for coverage.
      responses:
        '200':
          description: List of meta data for coverage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageMetaModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      termination_reasons:
                      - id: 7
                        lookup_code: divorce
                        name: Divorce (COBRA)
                      - id: 8
                        lookup_code: overage_child
                        name: Child becomes ineligible (COBRA)
                      - id: 21
                        lookup_code: dependent_death
                        name: Dependent Death (Non-COBRA)
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Not enough or too many segments
                    data: []
        '401':
          description: Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 401
                      message: Signature has expired
                      error_code: invalid_token
                    data: []
        '403':
          description: Access error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 403
                      message: Forbidden
                    data: []
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 404
                      message: Invalid coverage
                      error_code: 404
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoLinks500Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 500
                      message: Internal error
                    data: []
  /coverage/{coverage_id}:
    get:
      tags:
      - Coverage
      description: Retrieve individual coverage data.
      parameters:
      - name: coverage_id
        in: path
        description: The ID of the coverage.
        required: true
        schema:
          type: integer
          format: int64
      - name: plan_year
        in: query
        description: Plan year.
        required: false
        schema:
          type: string
          enum:
          - previous
          - current
          - next
      responses:
        '200':
          description: Individual coverage data response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      id: 21028866
                      org_benefit_id: 4066306
                      coverage_level_id: 139
                      termination_reason_id: 4
                      original_effective_date: 2018/05/29
                      change_effective_date: 2018/01/04
                      payment_change_effective_date: 2018/01/04
                      termination_date: 2018/05/28
                      org_plan_id: 6954498
                      subscriber_id: 8854530
                      subscriber_premium: '0.0'
                      org_premium: '0.0'
                      volume: '0.0'
                      org_fsa_amount: '0.0'
                      subscriber_fsa_amount: '0.0'
                      increments: 0
                      billing_premium: '0.0'
                      billing_fee: '0.0'
                      billing_fee2: '0.0'
                      imputed_income: '0.0'
                      req_volume: '0.0'
                      req_increments: '0.0'
                      req_subscriber_premium: '0.0'
                      req_org_premium: '0.0'
                      req_billing_premium: '0.0'
                      req_billing_fee: '0.0'
                      req_billing_fee2: '0.0'
                      gi_volume: '0.0'
                      gi_increments: '0.0'
                      waiting_for_eoi: false
                      req_imputed_income: '0.0'
                      dp_sub_imputed_income: '0.0'
                      dp_org_imputed_income: '0.0'
                      req_dp_sub_imputed_income: '0.0'
                      req_dp_org_imputed_income: '0.0'
                      election_effective_date: 2018/01/04
                      subscriber_election_amount: '0.0'
                      subscriber_pretax_premium: '0.0'
                      subscriber_posttax_premium: '0.0'
                      signature_date: 2018/05/29
                      req_org_plan_id: 6954498
                      req_coverage_level_id: 139
                      req_dependent_ids: []
                      req_subscriber_election_amount: '0.0'
                      req_subscriber_fsa_amount: '0.0'
                      req_org_fsa_amount: '0.0'
                      gi_dependent_ids: []
                      gi_subscriber_election_amount: '0.0'
                      waiting_for_doc_requests: false
                      bookkeeping_values:
                        cost_org_base_amount: 0
                        cost_org_match_amount: 1162
                        org_annual_base_amount: 0
                        org_annual_match_amount: 1162
                      org_benefit_name: Health Savings Account
                      benefit_lookup_code: hsa
                      coverage_level_name: Employee Only
                      plan_year_starts_on: 2018/01/04
                      plan_year_ends_on: 2019/01/03
                      coverage_type_name: Employee
                      benefit_class: contribution
                      beneficiary_required: Not Applicable
                      beneficiary_optional_admin: false
                      org_plan_name: Health Savings Account
                      first_name: Eli
                      last_name: Test
                      req_org_plan_name: Health Savings Account
                      req_coverage_level_name: Employee Only
                      survey_data:
                        coverage_id: 21028866
                        survey_benefit_name: Tobacco Survey
                        org_benefit_id: 4066306
                        question_response_data:
                          plan_id: 846850
                          question_text: Do you currently use tobacco products?
                          subscriber_ssn: 111222444
                          question_response:
                            response_text: 'Yes'
                            value: 'Yes'
                          time_answered: 05/29/201816:03:27
                          question_targeted_at: Subscriber
                          carrier_question_type: Actively At Work (Employee)
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Not enough or too many segments
                    data: []
        '401':
          description: Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 401
                      message: Signature has expired
                      error_code: invalid_token
                    data: []
        '403':
          description: Access error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 403
                      message: Forbidden
                    data: []
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 404
                      message: Requested route 'coverage' not found
                      error_code: route_not_found
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoLinks500Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 500
                      message: Internal error
                    data: []
    put:
      tags:
      - Coverage
      description: Update an individual coverage
      parameters:
      - name: coverage_id
        in: path
        description: The ID of the coverage to fetch.
        required: true
        schema:
          type: integer
          format: int64
      - name: plan_year
        in: query
        description: Plan year
        required: false
        schema:
          type: string
          enum:
          - previous
          - current
          - next
      - name: recalculate
        in: query
        description: Perform a recalculate of the coverage
        required: false
        schema:
          type: boolean
      - name: validate_volume
        in: query
        description: Perform the validation of the coverage
        required: false
        schema:
          type: boolean
      - name: recalculate_volume
        in: query
        description: Perform a volume recalculate of the coverage
        required: false
        schema:
          type: boolean
      - name: set_original_effective_date
        in: query
        description: Allow the setting of the original effective date
        required: false
        schema:
          type: string
          format: date
      - name: set_change_effective_date
        in: query
        description: Allow the setting of the change effective date
        required: false
        schema:
          type: string
          format: date
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CoverageModel'
        required: true
      responses:
        '200':
          description: Update coverage response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoveragesResponseOK'
              examples:
                response: {}
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Not enough or too many segments
                    data: []
        '401':
          description: Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 401
                      message: Signature has expired
                      error_code: invalid_token
                    data: []
        '403':
          description: Access error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 403
                      message: Forbidden
                    data: []
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 404
                      message: Requested route 'coverage' not found
                      error_code: route_not_found
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoLinks500Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 500
                      message: Internal error
                    data: []
  /coverage/subscriber/{subscriber_id}:
    get:
      tags:
      - Coverage
      description: Retrieve coverage data for an individual subscriber.
      parameters:
      - name: subscriber_id
        in: path
        description: The ID of the subscriber.
        required: true
        schema:
          type: integer
          format: int64
      - name: start_date
        in: query
        description: Start date of a date range of coverage changes.  ISO 8601 date or RFC 3339 date time date (ex. 2017-12-01 or 2017-12-01T12:30:30-06:00).
        required: false
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date of a date range of coverage changes.  ISO 8601 date or RFC 3339 date time (ex. 2017-12-01 or 2017-12-01T12:30:30-06:00).
        required: false
        schema:
          type: string
          format: date
      - name: plan_year
        in: query
        description: Plan year.
        required: false
        schema:
          type: string
          enum:
          - previous
          - current
          - next
      responses:
        '200':
          description: Coverage data for an individual subscriber.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      id: 21028866
                      org_benefit_id: 4066306
                      coverage_level_id: 139
                      termination_reason_id: 4
                      original_effective_date: 2018/05/29
                      change_effective_date: 2018/01/04
                      payment_change_effective_date: 2018/01/04
                      termination_date: 2018/05/28
                      org_plan_id: 6954498
                      subscriber_id: 8854530
                      subscriber_premium: '0.0'
                      org_premium: '0.0'
                      volume: '0.0'
                      org_fsa_amount: '0.0'
                      subscriber_fsa_amount: '0.0'
                      increments: 0
                      billing_premium: '0.0'
                      billing_fee: '0.0'
                      billing_fee2: '0.0'
                      imputed_income: '0.0'
                      req_volume: '0.0'
                      req_increments: '0.0'
                      req_subscriber_premium: '0.0'
                      req_org_premium: '0.0'
                      req_billing_premium: '0.0'
                      req_billing_fee: '0.0'
                      req_billing_fee2: '0.0'
                      gi_volume: '0.0'
                      gi_increments: '0.0'
                      waiting_for_eoi: false
                      req_imputed_income: '0.0'
                      dp_sub_imputed_income: '0.0'
                      dp_org_imputed_income: '0.0'
                      req_dp_sub_imputed_income: '0.0'
                      req_dp_org_imputed_income: '0.0'
                      election_effective_date: 2018/01/04
                      subscriber_election_amount: '0.0'
                      subscriber_pretax_premium: '0.0'
                      subscriber_posttax_premium: '0.0'
                      signature_date: 2018/05/29
                      req_org_plan_id: 6954498
                      req_coverage_level_id: 139
                      req_dependent_ids: []
                      req_subscriber_election_amount: '0.0'
                      req_subscriber_fsa_amount: '0.0'
                      req_org_fsa_amount: '0.0'
                      gi_dependent_ids: []
                      gi_subscriber_election_amount: '0.0'
                      waiting_for_doc_requests: false
                      bookkeeping_values:
                        cost_org_base_amount: 0
                        cost_org_match_amount: 1162
                        org_annual_base_amount: 0
                        org_annual_match_amount: 1162
                      org_benefit_name: Health Savings Account
                      benefit_lookup_code: hsa
                      coverage_level_name: Employee Only
                      plan_year_starts_on: 2018/01/04
                      plan_year_ends_on: 2019/01/03
                      coverage_type_name: Employee
                      benefit_class: contribution
                      beneficiary_required: Not Applicable
                      beneficiary_optional_admin: false
                      org_plan_name: Health Savings Account
                      first_name: Eli
                      last_name: Test
                      req_org_plan_name: Health Savings Account
                      req_coverage_level_name: Employee Only
                      survey_data:
                        coverage_id: 21028866
                        survey_benefit_name: Tobacco Survey
                        org_benefit_id: 4066306
                        question_response_data:
                          plan_id: 846850
                          question_text: Do you currently use tobacco products?
                          subscriber_ssn: 111222444
                          question_response:
                            response_text: 'Yes'
                            value: 'Yes'
                          time_answered: 05/29/201816:03:27
                          question_targeted_at: Subscriber
                          carrier_question_type: Actively At Work (Employee)
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Not enough or too many segments
                    data: []
        '401':
          description: Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 401
                      message: Signature has expired
                      error_code: invalid_token
                    data: []
        '403':
          description: Access error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 403
                      message: Forbidden
                    data: []
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 404
                      message: Invalid coverage
                      error_code: 404
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoLinks500Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 500
                      message: Internal error
                    data: []
  /coverage/subscriber/{subscriber_id}/terminate:
    put:
      tags:
      - Coverage
      description: Terminate all coverages for a subscriber.
      parameters:
      - name: subscriber_id
        in: path
        description: The ID of the subscriber.
        required: true
        schema:
          type: integer
          format: int64
      - name: plan_year
        in: query
        description: Plan year.
        required: false
        schema:
          type: string
          enum:
          - previous
          - current
          - next
      requestBody:
        description: The information used to terminate all coverages.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_8'
        required: true
      responses:
        '200':
          description: Terminate all coverages response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageWithPlanStructureModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data: []
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Not enough or too many segments
                    data: []
        '401':
          description: Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 401
                      message: Signature has expired
                      error_code: invalid_token
                    data: []
        '403':
          description: Access error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 403
                      message: Forbidden
                    data: []
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 404
                      message: Invalid coverage
                      error_code: 404
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoLinks500Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 500
                      message: Internal error
                    data: []
  /coverage/{coverage_id}/terminate:
    put:
      tags:
      - Coverage
      description: Terminate an individual coverage.
      parameters:
      - name: coverage_id
        in: path
        description: The ID of the coverage.
        required: true
        schema:
          type: integer
          format: int64
      - name: plan_year
        in: query
        description: Plan year.
        required: false
        schema:
          type: string
          enum:
          - previous
          - current
          - next
      - name: set_change_effective_date
        in: query
        description: Allow the setting of the change effective date.
        required: false
        schema:
          type: string
          format: date
      requestBody:
        description: The information used to terminate a coverage.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_9'
        required: true
      responses:
        '200':
          description: Teminate a coverage response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminateResponseOK'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      valid_count: 0
                      failed_count: 1
                      failed_rows:
                        errors: termination_date missing, termination_reason_id missing
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Not enough or too many segments
                    data: []
        '401':
          description: Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
              examples:
                response:
                  value:
                    s

# --- truncated at 32 KB (195 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/plansource/refs/heads/main/openapi/plansource-coverage-api-openapi.yml