PlanSource Collections API

openapi: 3.2.0
info:
  title: Plansource Admin Collections 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: Collections
  description: Collections of objects.
paths:
  /payroll_coverages_subscribers:
    get:
      tags:
      - Collections
      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_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
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                response:
                  value:
                    status: failure
                    errors:
                      http_status: 400
                      message: No Start Date (params[:start_date] in the request.
                    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_subcribers' 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: []
  /subscribers:
    get:
      tags:
      - Collections
      description: Retrieve data for all subscribers.
      parameters:
      - 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: page
        in: query
        description: Set to page number. Large responses are parsed into a maximum of 500 subscribers or the per_page value for large responses of subscribers.
        required: false
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Override of the maximum of 500 subscribers 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
      responses:
        '200':
          description: Multiple subscriber retrieval 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
                      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: 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: 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 'subscribe' 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:
      - Collections
      description: Update data for all subscribers.
      parameters:
      - name: is_custom_id
        in: query
        description: Set to true if the {id} is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        description: The subscribers to be updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_5'
        required: true
      responses:
        '200':
          description: Subscribers update 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
                      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: 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: 'undefined method `+'' for #<NoMethodError: undefined method `gsub'' for nil:NilClass>'
                    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' 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: []
    post:
      tags:
      - Collections
      description: Create subscriber resources.
      parameters:
      - 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:
        $ref: '#/components/requestBodies/Body'
      responses:
        '200':
          description: Multiple subscriber create 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
                      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: 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: Invalid value for employee_number.  The valid values are '',1,2,3.
                      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 'subscribe' 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: []
  /subscribers/terminate:
    put:
      tags:
      - Collections
      description: Terminate subscriber resources.
      parameters:
      - name: is_custom_id
        in: query
        description: Set to true if the {id} is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_6'
        required: true
      responses:
        '200':
          description: Subscribers 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/13
                      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: 4
                      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 'subscribers/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: []
  /subscribers/rehire:
    put:
      tags:
      - Collections
      description: Rehire subscriber resources.
      parameters:
      - name: is_custom_id
        in: query
        description: Set to true if the {id} is customer generated.
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_7'
        required: true
      responses:
        '200':
          description: Subscribers 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_dat

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