PlanSource Demographic API

openapi: 3.2.0
info:
  title: Plansource Admin Demographic 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: Demographic
  description: Subscribers, their dependents and beneficiaries.
paths:
  /subscriber:
    post:
      tags:
      - Demographic
      description: Create a subscriber resource.
      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: 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: A user_name or first_name and last_name is required.
                      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 'ubscriber' 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/meta:
    get:
      tags:
      - Demographic
      description: Retrieve meta data for subscriber.
      responses:
        '200':
          description: List of meta data for subscriber.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaModel'
              examples:
                response:
                  value:
                    status: success
                    errors: []
                    data:
                      payroll_schedules:
                        id: 119298
                        name: Monthly
                        lookup_code: monthly_1
                      is_smoker:
                        update: true
                        required: false
                        caption: Tobacco User
                        data_type: STRING
                        validation_data:
                        - 'YES'
                        - 'YES'
                      employment_level:
                        update: true
                        required: false
                        caption: Employment Level
                        data_type: STRING
                        validation_data:
                        - F
                        - F
                      state:
                        update: true
                        required: false
                        caption: State/Province
                        data_type: STRING
                        validation_data:
                        - Alabama
                        - AL
                      country:
                        update: true
                        required: false
                        caption: Country
                        data_type: STRING
                        validation_data:
                        - Lebanon
                        - Lebanon
                      gender:
                        update: true
                        required: false
                        caption: Gender
                        data_type: STRING
                        validation_data:
                        - Male
                        - M
                      marital_status:
                        update: true
                        required: false
                        caption: Marital Status
                        data_type: STRING
                        validation_data:
                        - Married
                        - M
                      org_payroll_id:
                        update: true
                        required: false
                        caption: Payroll Schedule
                        data_type: NUMBER
                        validation_data:
                        - Monthly
                        - 119298
                      termination_reason:
                        update: true
                        required: false
                        caption: Termination Reason
                        data_type: STRING
                        validation_data:
                          lookup_code: death
                          name: Death (COBRA)
                          description: Death of Employee
        '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: 'No employee with id: met found'
                      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/{id}:
    get:
      tags:
      - Demographic
      description: Retrieve data for a subscriber.
      parameters:
      - name: id
        in: path
        description: The ID of the subscriber.
        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
      responses:
        '200':
          description: 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'
        '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: 'No employee with id: 8854530 found'
                      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: []
    put:
      tags:
      - Demographic
      description: Update data for a subscriber.
      parameters:
      - name: id
        in: path
        description: The ID of the subscriber.
        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:
        $ref: '#/components/requestBodies/Body'
      responses:
        '200':
          description: Subscriber 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: State must be a valid State abbreviation.
                      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 'subscribr/12196354' 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}/terminate:
    put:
      tags:
      - Demographic
      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:
      - Demographic
      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
                    

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