PlanSource Processing API

openapi: 3.2.0
info:
  title: Plansource Admin Processing 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: Processing
  description: Endpoints used for processing data, producing a result, and/or running a sequence of actions.
paths:
  /subscriber/{id}/terminate:
    put:
      tags:
      - Processing
      description: Terminate a subscriber.
      parameters:
      - name: id
        in: path
        description: The ID of the subscriber to terminate.
        required: true
        schema:
          type: integer
          format: int64
      - name: is_custom_id
        in: query
        description: Set to true if the {id} in the path is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body'
        required: true
      responses:
        '200':
          description: Subscriber terminate response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      links:
                        href: /admin/subscriber/12186626
                        rel: self
                      id: 12186626
                      first_name: John
                      last_name: Test
                      middle_name: M
                      address_1: 1234TestSt.
                      address_2: ''
                      city: Orlando
                      state: FL
                      zip_code: '32801'
                      country: United States
                      home_phone: '4071231234'
                      work_phone: '4071231234'
                      cell_phone: '4071231234'
                      gender: M
                      hire_date: 2006/06/13
                      birthdate: 1990/03/11
                      termination_date: 2018/04/08
                      union_code: HR
                      pay_rate: '40.0'
                      org_payroll_id: '563'
                      employee_number: '2'
                      public_id: 988618
                      marital_status: M
                      division: A
                      location: FLORIDA
                      org_class: HOURLY
                      business_title: MR
                      original_hire_date: 2006/06/13
                      current_salary_effective_on: 2006/06/13
                      current_salary: '70000.0'
                      subscriber_status_id: 15
                      status_changed_at: '2006/06/1300: 00: 00-0400'
                      status_starts_on: 2006/06/13
                      benefits_start_date: 2006/06/13
                      test_employee: false
                      is_voluntary_termination: true
                      hide_from_payroll: false
                      termination_reason_id: 3
                      ssn_exported: false
                      shareholder: false
                      owner: false
                      exclude_from_batch_import: false
                      user_name: jtest_7
                      attempted_logon_count: 0
                      benefit_salaries:
                      - org_plan_year_id: 18791472
                        starts_on: '2019-01-01T00:00:00.000Z'
                        ends_on: '2019-12-31T00:00:00.000Z'
                        benefit_salary: '70000.0'
                        benefit_salary2: '75000.0'
                      - org_plan_year_id: 18791492
                        starts_on: '2020-01-01T00:00:00.000Z'
                        ends_on: '2020-12-31T00:00:00.000Z'
                        benefit_salary: '80000.0'
                        benefit_salary2: '85000.0'
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Cannot perform action as the employee is terminated
                      error_code: 400
                    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 'subscriber/12187650/terminat' 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: []
  /subscriber/{id}/rehire:
    put:
      tags:
      - Processing
      description: Rehire a subscriber.
      parameters:
      - name: id
        in: path
        description: The ID of the subscriber to rehire.
        required: true
        schema:
          type: integer
          format: int64
      - name: is_custom_id
        in: query
        description: Set to true if the {id} in the path is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_1'
        required: true
      responses:
        '200':
          description: Subscriber rehire response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      links:
                        href: /admin/subscriber/12186626
                        rel: self
                      id: 12186626
                      first_name: John
                      last_name: Test
                      middle_name: M
                      address_1: 1234TestSt.
                      address_2: ''
                      city: Orlando
                      state: FL
                      zip_code: '32801'
                      country: United States
                      home_phone: '4071231234'
                      work_phone: '4071231234'
                      cell_phone: '4071231234'
                      gender: M
                      hire_date: 2018/07/08
                      birthdate: 1990/03/11
                      union_code: HR
                      pay_rate: '40.0'
                      org_payroll_id: '563'
                      employee_number: '2'
                      public_id: 988618
                      marital_status: M
                      division: A
                      location: FLORIDA
                      org_class: HOURLY
                      business_title: MR
                      original_hire_date: 2006/06/13
                      current_salary_effective_on: 2006/06/13
                      current_salary: '70000.0'
                      subscriber_status_id: 15
                      status_changed_at: '2006/06/1300: 00: 00-0400'
                      status_starts_on: 2018/07/08
                      benefits_start_date: 2018/07/08
                      test_employee: false
                      is_voluntary_termination: false
                      hide_from_payroll: false
                      ssn_exported: false
                      shareholder: false
                      owner: false
                      exclude_from_batch_import: false
                      user_name: jtest_7
                      attempted_logon_count: 0
                      benefit_salaries:
                      - org_plan_year_id: 18791472
                        starts_on: '2019-01-01T00:00:00.000Z'
                        ends_on: '2019-12-31T00:00:00.000Z'
                        benefit_salary: '70000.0'
                        benefit_salary2: '75000.0'
                      - org_plan_year_id: 18791492
                        starts_on: '2020-01-01T00:00:00.000Z'
                        ends_on: '2020-12-31T00:00:00.000Z'
                        benefit_salary: '80000.0'
                        benefit_salary2: '85000.0'
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: Cannot perform action as the employee is not terminated
                      error_code: 400
                    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 'subscriber/12187650/rehir' 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: []
  /subscriber/{subscriber_id}/dependent/{id}/deactivate:
    put:
      tags:
      - Processing
      description: Deactivate a dependent.
      parameters:
      - name: subscriber_id
        in: path
        description: The ID of the subscriber.
        required: true
        schema:
          type: integer
          format: int64
      - name: id
        in: path
        description: The ID of the dependent to deactivate.
        required: true
        schema:
          type: integer
          format: int64
      - name: is_custom_id
        in: query
        description: Set to true if the {subscriber_id} in the path is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_4'
        required: true
      responses:
        '200':
          description: Dependent deactivate response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DependentModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      links:
                        href: /admin/subscriber/12206082/dependent/2078210
                        rel: self
                      id: 2078210
                      public_id: 2078210
                      ssn: XXX-XX-8782
                      first_name: TestFirst
                      middle_name: TestMiddle
                      last_name: TestLast
                      name_suffix: Mr.
                      hide_dependent_on_termination: false
                      termination_reason_id: 7
                      medicare_effective_date: 2010/01/01
                      medicare_plan: PART A
                      medicare_reason: AGE
                      medicare_termination_date: 2009/01/01
                      birthdate: 2007/07/08
                      gender: M
                      relationship_code: child
                      lives_at_home: false
                      address_1: 111 Lane Dr.
                      address_2: Apt. 21
                      city: Orlando
                      state: FL
                      zip_code: '34786'
                      country: United States
                      is_smoker: 'NO'
                      verified: true
                      verification_expires_on: 2009/01/01
                      termination_date: 2018/01/04
                      udef_1: custom
                      udef_2: custom
                      udef_3: custom
                      udef_4: custom
                      udef_5: custom
                      udef_6: custom
                      udef_7: custom
                      udef_8: custom
                      udef_9: custom
                      udef_10: custom
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: The dependent cannot be terminated.  The dependent is already terminated.
                      error_code: 400
                    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: A termination_reason is required.  Please check the meta and pass the lookup_code in the termination_reason variable.
                      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: []
  /subscriber/{subscriber_id}/dependent/{id}/reactivate:
    put:
      tags:
      - Processing
      description: Reactivate a dependent.
      parameters:
      - name: subscriber_id
        in: path
        description: The ID of the subscriber.
        required: true
        schema:
          type: integer
          format: int64
      - name: id
        in: path
        description: The ID of the dependent to reactivate.
        required: true
        schema:
          type: integer
          format: int64
      - name: is_custom_id
        in: query
        description: Set to true if the {subscriber_id} in the path is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Dependent reactivate response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DependentModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      links:
                        href: /admin/subscriber/12206082/dependent/2078210
                        rel: self
                      id: 2078210
                      public_id: 2078210
                      ssn: XXX-XX-8782
                      first_name: TestFirst
                      middle_name: TestMiddle
                      last_name: TestLast
                      name_suffix: Mr.
                      hide_dependent_on_termination: false
                      termination_reason_id: 7
                      medicare_effective_date: 2010/01/01
                      medicare_plan: PART A
                      medicare_reason: AGE
                      medicare_termination_date: 2009/01/01
                      birthdate: 2007/07/08
                      gender: M
                      relationship_code: child
                      lives_at_home: false
                      address_1: 111 Lane Dr.
                      address_2: Apt. 21
                      city: Orlando
                      state: FL
                      zip_code: '34786'
                      country: United States
                      is_smoker: 'NO'
                      verified: true
                      verification_expires_on: 2009/01/01
                      udef_1: custom
                      udef_2: custom
                      udef_3: custom
                      udef_4: custom
                      udef_5: custom
                      udef_6: custom
                      udef_7: custom
                      udef_8: custom
                      udef_9: custom
                      udef_10: custom
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: The dependent cannot be reactivated.  The dependent is already active.
                      error_code: 400
                    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 'subscriber/8854530/dependent/2079234/reactivat' not found
                      error_code: route_not_found
        '500':
          description: An internal InternalServerError has occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoLinks500Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 500
                      message: Internal error
                    data: []
  /payroll_coverages_subscriber/{id}:
    get:
      tags:
      - Processing
      description: Retrieve payroll coverages for a subscriber.
      parameters:
      - name: 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 payroll changes.  ISO 8601 date or RFC 3339 date time date (ex. 2017-12-01 or 2017-12-01T12:30:30-06:00).
        required: true
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date of a date range of payroll changes.  ISO 8601 date or RFC 3339 date time (ex. 2017-12-01 or 2017-12-01T12:30:30-06:00).
        required: true
        schema:
          type: string
          format: date
      - name: is_custom_id
        in: query
        description: Set to true if the {id} in the path is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      - name: current
        in: query
        description: Return only the subscriber's current coverage records.
        required: false
        schema:
          type: boolean
      - name: previous
        in: query
        description: Return only the subscriber's coverage records that are immediately prior to the current record.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Payroll coverages for a subscriber response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollCoveragesSubscriberModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      id: 8854530
                      subscriber_code: ''
                      first_name: Ted
                      middle_name: M
                      last_name: Mosby
                      ssn: 123-12-1234
                      subscriber_pay_frequency: Biweekly (26 per year)
                      subscriber_total_paydays: 26
                      organization_id: 652
                      org_plan_year_starts: 2018/01/04
                      org_plan_year_ends: 2019/01/03
                      benefit_name: Medical
                      benefit_lookup_code: medical
                      plan_name: Decline
                      coverage_level: Decline
                      subscriber_premium: '0.0'
                      org_premium: '0.0'
                      imputed_income: '0.0'
                      subscriber_pretax_premium: '0.0'
                      subscriber_posttax_premium: '0.0'
                      tax_treatment: posttax
                      volume: '0.0'
                      org_fsa_amount: '0.0'
                      subscriber_fsa_amount: '0.0'
                      original_effective_date: '2018-01-04T00:00:00.000Z'
                      change_effective_date: '2018-01-04T00:00:00.000Z'
                      dp_sub_imputed_income: '0.0'
                      dp_org_imputed_income: '0.0'
                      current: CA
                      updated_at: '2018-05-29T19:59:55.000Z'
                      created_at: '2018-05-29T15:31:25.000Z'
                      termination_date: 2018/01/03
                      termination_reason: Subscriber voluntarily waived coverage
                      test_employee: false
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: start_date date is not a valid YYYY-MM-DD date format.
                    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 'payroll_coverages_subscribr/8854530' 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: []
  /payroll_coverages_subscribers:
    get:
      tags:
      - Processing
      description: Retrieve payroll coverages for all subscribers in the organization.
      parameters:
      - name: start_date
        in: query
        description: Start date of a date range of payroll changes.  ISO 8601 date or RFC 3339 date time date (ex. 2017-12-01 or 2017-12-01T12:30:30-06:00).
        required: true
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date of a date range of payroll changes.  ISO 8601 date or RFC 3339 date time (ex. 2017-12-01 or 2017-12-01T12:30:30-06:00).
        required: true
        schema:
          type: string
          format: date
      - name: page
        in: query
        description: Set to page number. Large responses are parsed into a maximum of 500 records or the per_page value for large responses.
        required: false
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Override of the maximum of 500 records returned in a response.
        required: false
        schema:
          type: integer
          default: 500
      - name: include_test
        in: query
        description: Include test employees.
        required: false
        schema:
          type: boolean
          default: false
      - name: current
        in: query
        description: Return only the subscriber's current coverage records.
        required: false
        schema:
          type: boolean
      - name: previous
        in: query
        description: Return only the subscriber's coverage records that are immediately prior to the current record.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Payroll coverages for all subscribers in the organization response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollCoveragesSubscriberModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      total: 6,
                      per_page: 1,
                      links:
                      - href: /admin/payroll_coverages_subscribers?start_date=2019-01-01&end_date=2019-12-31&page=1&per_page=1
                        rel: first
                      - href: /admin/payroll_coverages_subscribers?start_date=2019-01-01&end_date=2019-12-31&page=1&per_page=1
                        rel: current
                      - href: /admin/payroll_coverages_subscribers?start_date=2019-01-01&end_date=2019-12-31&page=2&per_page=1
                        rel: next
                      - href: /admin/payroll_coverages_subscribers?start_date=2019-01-01&end_date=2019-12-31&page=6&per_page=1
                        rel: last
                      link:
                        href: /admin/subscriber/8854530?start_date=2019-01-01&end_date=2019-12-31
                        rel: self
                      id: 8854530
                      subscriber_code: ''
                      first_name: Ted
                      middle_name: M
                      last_name: Mosby
                      ssn: 123-12-1234
                      subscriber_pay_frequency: Biweekly (26 per year)
                      subscriber_total_paydays: 26
                      organization_id: 652
                      org_plan_year_starts: 2018/01/04
                      org_plan_

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