Class: VitableConnect::Employers::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/VitableConnect/employers/client.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ void

Parameters:



9
10
11
 
# File 'lib/VitableConnect/employers/client.rb', line 9

def initialize(client:)
  @client = client
end

Instance Method Details

#create(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerResponse

Creates a new employer for the authenticated organization. Requires employer name, legal name, EIN, email, and address information. Returns the created employer with its assigned ID.

Examples:

client.employers.create(
  name: "NewCo Industries",
  legal_name: "NewCo Industries LLC",
  ein: "12-3456789",
  email: "[email protected]",
  address: {
    address_line1: "789 Business Blvd",
    address_line2: "Floor 5",
    city: "Seattle",
    state: "WA",
    zipcode: "98101"
  },
  phone_number: "2065550100",
  reference_id: "partner-emp-001"
)

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :vitable_organization (String, nil)

Returns:



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/VitableConnect/employers/client.rb', line 120

def create(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  request_data = VitableConnect::Employers::Types::CreateEmployerRequest.new(params).to_h
  non_body_param_names = %w[X-Vitable-Organization]
  body = request_data.except(*non_body_param_names)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v1/employers",
    headers: headers,
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#ensure_payroll_integration_email(request_options: {}, **params) ⇒ VitableConnect::Types::PayrollIntegrationEmailResponse

Provision and return the employer's payroll integration email.

Examples:

client.employers.ensure_payroll_integration_email(employer_id: "empr_abc123def456")

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
 
# File 'lib/VitableConnect/employers/client.rb', line 873

def ensure_payroll_integration_email(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "PUT",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/payroll-integration-email",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::PayrollIntegrationEmailResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#get(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerResponse

Retrieves detailed information for a specific employer by ID. The employer must belong to the authenticated organization.

Examples:

client.employers.get(employer_id: "empr_abc123def456")

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/VitableConnect/employers/client.rb', line 168

def get(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#get_benefit_plan_year(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerBenefitPlanYearResponse

Returns one benefit plan year in full — its benefit details plus the per-benefit enrollment rate and SPD link — addressed by its benefit_plan_year_id. The caller must be authorized for the employer; an unknown or unauthorized plan year returns 404.

Examples:

client.employers.get_benefit_plan_year(
  employer_id: "empr_abc123def456",
  benefit_plan_year_id: "plyr_abc123def456"
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/VitableConnect/employers/client.rb', line 308

def get_benefit_plan_year(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/benefit-plan-years/#{URI.encode_uri_component(params[:benefit_plan_year_id].to_s)}",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerBenefitPlanYearResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#get_hris(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerHrisResponse

Returns the employer's HRIS connection — provider, status, last sync, and synced row count — or null when the employer has no integration. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

Examples:

client.employers.get_hris(employer_id: "empr_abc123def456")

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
 
# File 'lib/VitableConnect/employers/client.rb', line 566

def get_hris(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/hris",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerHrisResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#get_invoice_pdf(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerInvoicePdfResponse

Returns the time-limited PDF download link for a single invoice belonging to the employer's billing customer. invoice_id is the external Chargebee id (not a prefixed UUID). The caller must be authorized for the employer; an unknown or unauthorized employer or invoice returns 404.

Examples:

client.employers.get_invoice_pdf(
  employer_id: "empr_abc123def456",
  invoice_id: "INV-00042"
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
 
# File 'lib/VitableConnect/employers/client.rb', line 668

def get_invoice_pdf(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/invoices/#{URI.encode_uri_component(params[:invoice_id].to_s)}/pdf",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerInvoicePdfResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#get_payroll_access_setup(request_options: {}, **params) ⇒ VitableConnect::Types::PayrollAccessSetupStatusResponse

Return whether the employer has submitted payroll access setup.

Examples:

client.employers.get_payroll_access_setup(employer_id: "empr_abc123def456")

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
 
# File 'lib/VitableConnect/employers/client.rb', line 710

def get_payroll_access_setup(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/payroll-access-setup",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::PayrollAccessSetupStatusResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#list(request_options: {}, **params) ⇒ VitableConnect::Types::OrganizationEmployerListResponse

Returns the caller's employer book — every employer with its computed columns (enrollment-rate summary, benefit-family tags, HRIS connection, benefit-lifecycle stage) merged with the employer's flat CRM fields (legal name, EIN, contact, address, timestamps). The book is derived from the authenticated principal: one organization's employers, or every organization's for a caller whose reach is not a single organization. Supports search by display name, legal name, or exact EIN, employer id or contact email, benefit-family/lifecycle/HRIS filters, and page/limit pagination.

Examples:

client.employers.list(
  limit: 20,
  page: 1
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/VitableConnect/employers/client.rb', line 44

def list(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["benefit_family"] = params[:benefit_family] if params.key?(:benefit_family)
  query_params["benefit_lifecycle_stage"] = params[:benefit_lifecycle_stage] if params.key?(:benefit_lifecycle_stage)
  query_params["hris_provider"] = params[:hris_provider] if params.key?(:hris_provider)
  query_params["hris_status"] = params[:hris_status] if params.key?(:hris_status)
  query_params["include_cancelled"] = params[:include_cancelled] if params.key?(:include_cancelled)
  query_params["limit"] = params[:limit] if params.key?(:limit)
  query_params["page"] = params[:page] if params.key?(:page)
  query_params["search"] = params[:search] if params.key?(:search)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  VitableConnect::Internal::OffsetItemIterator.new(
    initial_page: query_params["page"],
    item_field: :data,
    has_next_field: nil,
    step: false
  ) do |next_page|
    query_params["page"] = next_page
    request = VitableConnect::Internal::JSON::Request.new(
      base_url: request_options[:base_url],
      method: "GET",
      path: "v1/employers",
      headers: headers,
      query: query_params,
      request_options: request_options
    )
    begin
      response = @client.send(request)
    rescue Net::HTTPRequestTimeout
      raise VitableConnect::Errors::TimeoutError
    end
    code = response.code.to_i
    if code.between?(200, 299)
      parsed_response = VitableConnect::Types::OrganizationEmployerListResponse.load(response.body)
      [parsed_response, response]
    else
      error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(response.body, code: code)
    end
  end
end

#list_benefit_plan_year_enrollments(request_options: {}, **params) ⇒ VitableConnect::Types::PlanYearEnrollmentListResponse

Returns a paginated list of every member with an enrollment in one of an employer's plan years, any election status: what they elected, where their coverage stands, dependent count, carrier, plan, tier, and the plan's total monthly cost. The caller must be authorized for the employer empr_<...>; an unknown or unauthorized employer, or an unknown plan year plyr_<...>, returns 404.

Examples:

client.employers.list_benefit_plan_year_enrollments(
  employer_id: "empr_abc123def456",
  benefit_plan_year_id: "plyr_abc123def456",
  limit: 20,
  page: 1
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
 
# File 'lib/VitableConnect/employers/client.rb', line 363

def list_benefit_plan_year_enrollments(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["election_status"] = params[:election_status] if params.key?(:election_status)
  query_params["limit"] = params[:limit] if params.key?(:limit)
  query_params["page"] = params[:page] if params.key?(:page)
  query_params["search"] = params[:search] if params.key?(:search)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  VitableConnect::Internal::OffsetItemIterator.new(
    initial_page: query_params["page"],
    item_field: :data,
    has_next_field: nil,
    step: false
  ) do |next_page|
    query_params["page"] = next_page
    request = VitableConnect::Internal::JSON::Request.new(
      base_url: request_options[:base_url],
      method: "GET",
      path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/benefit-plan-years/#{URI.encode_uri_component(params[:benefit_plan_year_id].to_s)}/enrollments",
      headers: headers,
      query: query_params,
      request_options: request_options
    )
    begin
      response = @client.send(request)
    rescue Net::HTTPRequestTimeout
      raise VitableConnect::Errors::TimeoutError
    end
    code = response.code.to_i
    if code.between?(200, 299)
      parsed_response = VitableConnect::Types::PlanYearEnrollmentListResponse.load(response.body)
      [parsed_response, response]
    else
      error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(response.body, code: code)
    end
  end
end

#list_benefit_plan_years(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerBenefitPlanYearsListResponse

Returns the employer's benefit plan years (all years, or one when year is given), each with its benefits, offered states, benefit families, and the year-level enrollment roll-up. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

Examples:

client.employers.list_benefit_plan_years(employer_id: "empr_abc123def456")

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/VitableConnect/employers/client.rb', line 260

def list_benefit_plan_years(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/benefit-plan-years",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerBenefitPlanYearsListResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#list_employees(request_options: {}, **params) ⇒ VitableConnect::Types::EmployeeListResponse

Retrieves a paginated list of employees for a specific employer. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404. Results are paginated using page and limit parameters and can be narrowed with a case-insensitive search (first name, last name, or email) and an employment_status filter (active or terminated). Each employee includes payroll deductions from the most recent statement period. When a new deduction statement is generated, previous period deductions are replaced.

Examples:

client.employers.list_employees(
  employer_id: "empr_abc123def456",
  limit: 20,
  page: 1,
  search: "jane"
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
 
# File 'lib/VitableConnect/employers/client.rb', line 506

def list_employees(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["employment_status"] = params[:employment_status] if params.key?(:employment_status)
  query_params["limit"] = params[:limit] if params.key?(:limit)
  query_params["page"] = params[:page] if params.key?(:page)
  query_params["search"] = params[:search] if params.key?(:search)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  VitableConnect::Internal::OffsetItemIterator.new(
    initial_page: query_params["page"],
    item_field: :data,
    has_next_field: nil,
    step: false
  ) do |next_page|
    query_params["page"] = next_page
    request = VitableConnect::Internal::JSON::Request.new(
      base_url: request_options[:base_url],
      method: "GET",
      path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/employees",
      headers: headers,
      query: query_params,
      request_options: request_options
    )
    begin
      response = @client.send(request)
    rescue Net::HTTPRequestTimeout
      raise VitableConnect::Errors::TimeoutError
    end
    code = response.code.to_i
    if code.between?(200, 299)
      parsed_response = VitableConnect::Types::EmployeeListResponse.load(response.body)
      [parsed_response, response]
    else
      error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(response.body, code: code)
    end
  end
end

#list_hris_providers(request_options: {}, **params) ⇒ VitableConnect::Types::OrganizationHrisProvidersResponse

Returns the distinct HRIS/payroll providers across the same book GET /v1/employers returns, sorted for display. Use these as the values for the employers list's hris_provider filter — filter on provider, show provider_label. The stored providers are free text, so they cannot be enumerated in advance.

Examples:

client.employers.list_hris_providers

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :vitable_organization (String, nil)

Returns:



967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
 
# File 'lib/VitableConnect/employers/client.rb', line 967

def list_hris_providers(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/hris-providers",
    headers: headers,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::OrganizationHrisProvidersResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#list_invoices(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerInvoicesListResponse

Returns a cursor-paginated page of the employer's billing invoices, newest first. Pass the next_offset from a previous page as offset to fetch the next page. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

Examples:

client.employers.list_invoices(
  employer_id: "empr_abc123def456",
  limit: 20
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
 
# File 'lib/VitableConnect/employers/client.rb', line 615

def list_invoices(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["limit"] = params[:limit] if params.key?(:limit)
  query_params["offset"] = params[:offset] if params.key?(:offset)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/invoices",
    headers: headers,
    query: query_params,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerInvoicesListResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#list_payroll_deduction_statements(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerPayrollDeductionStatementListResponse

Returns a paginated list of the employer's payroll-deduction statements, newest period first, each with its period, generation date, distinct employee count, total deduction, change-file link, and deduction frequency. Statements superseded by a later correction are excluded. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

Examples:

client.employers.list_payroll_deduction_statements(
  employer_id: "empr_abc123def456",
  limit: 20,
  page: 1
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
 
# File 'lib/VitableConnect/employers/client.rb', line 817

def list_payroll_deduction_statements(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["limit"] = params[:limit] if params.key?(:limit)
  query_params["page"] = params[:page] if params.key?(:page)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  VitableConnect::Internal::OffsetItemIterator.new(
    initial_page: query_params["page"],
    item_field: :data,
    has_next_field: nil,
    step: false
  ) do |next_page|
    query_params["page"] = next_page
    request = VitableConnect::Internal::JSON::Request.new(
      base_url: request_options[:base_url],
      method: "GET",
      path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/payroll-deduction-statements",
      headers: headers,
      query: query_params,
      request_options: request_options
    )
    begin
      response = @client.send(request)
    rescue Net::HTTPRequestTimeout
      raise VitableConnect::Errors::TimeoutError
    end
    code = response.code.to_i
    if code.between?(200, 299)
      parsed_response = VitableConnect::Types::EmployerPayrollDeductionStatementListResponse.load(response.body)
      [parsed_response, response]
    else
      error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(response.body, code: code)
    end
  end
end

#submit_census_sync(request_options: {}, **params) ⇒ VitableConnect::Types::CensusSyncDetailResponse

Submits a census sync payload for the specified employer. The employees in the payload will be queued for processing. Returns an accepted response with the timestamp of acceptance.

Examples:

client.employers.submit_census_sync(
  employer_id: "empr_abc123def456",
  employees: [{
    reference_id: "EMP-001",
    first_name: "Jane",
    last_name: "Doe",
    date_of_birth: "1990-05-15",
    email: "[email protected]",
    phone: "4155550100",
    address: {
      address_line1: "123 Main Street",
      address_line2: "Apt 4B",
      city: "San Francisco",
      state: "CA",
      zipcode: "94102"
    },
    start_date: "2024-01-15",
    employee_class: "Full Time",
    compensation_type: "Salary"
  }, {
    first_name: "John",
    last_name: "Smith",
    date_of_birth: "1985-11-20",
    email: "[email protected]",
    phone: "4155550101",
    start_date: "2024-03-01",
    employee_class: "Part Time",
    compensation_type: "Hourly"
  }]
)

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
 
# File 'lib/VitableConnect/employers/client.rb', line 450

def submit_census_sync(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  request_data = VitableConnect::Employers::Types::CensusSyncRequest.new(params).to_h
  non_body_param_names = %w[employer_id]
  body = request_data.except(*non_body_param_names)

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/census-sync",
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::CensusSyncDetailResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#submit_payroll_access_setup(request_options: {}, **params) ⇒ VitableConnect::Types::PayrollAccessSetupStatusResponse

Submit the employer's payroll access setup answers.

Examples:

client.employers.submit_payroll_access_setup(
  employer_id: "empr_abc123def456",
  employees_in_payroll_acknowledged: true,
  payroll_data_impacts_eligibility_acknowledged: true,
  classifications_accurate: true,
  all_benefit_eligible_employees_present: true,
  is_controlled_group: true,
  access_method: "SELF_SETUP",
  has_additional_payroll_system: true
)

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
 
# File 'lib/VitableConnect/employers/client.rb', line 761

def submit_payroll_access_setup(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  request_data = VitableConnect::Employers::Types::SubmitPayrollAccessSetupRequest.new(params).to_h
  non_body_param_names = %w[employer_id X-Vitable-Organization]
  body = request_data.except(*non_body_param_names)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "PUT",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/payroll-access-setup",
    headers: headers,
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::PayrollAccessSetupStatusResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#update(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerResponse

Updates an existing employer. All fields are optional — only provided fields are updated. PO Box addresses are rejected.

Examples:

client.employers.update(employer_id: "empr_abc123def456")

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/VitableConnect/employers/client.rb', line 211

def update(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  request_data = VitableConnect::Employers::Types::UpdateEmployerRequest.new(params).to_h
  non_body_param_names = %w[employer_id X-Vitable-Organization]
  body = request_data.except(*non_body_param_names)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "PUT",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}",
    headers: headers,
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#update_settings(request_options: {}, **params) ⇒ VitableConnect::Types::EmployerSettingsResponse

Updates configuration settings for a specific employer. The employer must belong to the authenticated organization.

Examples:

client.employers.update_settings(
  employer_id: "empr_abc123def456",
  pay_frequency: "bi_weekly"
)

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
 
# File 'lib/VitableConnect/employers/client.rb', line 919

def update_settings(request_options: {}, **params)
  params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
  request_data = VitableConnect::Employers::Types::UpdateEmployerSettingsRequest.new(params).to_h
  non_body_param_names = %w[employer_id X-Vitable-Organization]
  body = request_data.except(*non_body_param_names)

  headers = {}
  headers["X-Vitable-Organization"] = params[:vitable_organization] if params[:vitable_organization]

  request = VitableConnect::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "PUT",
    path: "v1/employers/#{URI.encode_uri_component(params[:employer_id].to_s)}/settings",
    headers: headers,
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise VitableConnect::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    VitableConnect::Types::EmployerSettingsResponse.load(response.body)
  else
    error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end