Finch universal HRIS Ruby client

Unofficial client library for working with the Finch API

Installation

Add this line to your application's Gemfile:

gem 'finch-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install finch-client

Setup

You'll need a Finch developer account which will give you a client ID and client secret. Once this gem has been installed and you have the required credentials, you must place Finch configuration early in your app's boot process (eg: a Rails initializer):

Finch::Client.configure do |config|
  config.client_id = '...'
  config.client_secret = '...'
  # Set this to `false` in production and `true` in any testing environment
  config.sandbox = false
end

Usage

Obtaining an access token

This is a mandatory first step toward interacting with the Finch API. The access token handshake informs the user of the permissions being requested and requires their consent to proceed, similar to any OAuth-like flow. You'll need to know your redirect URI, permissions, and any additional configuration you may need.

This gem includes a helper to generate the Finch authorization URL that you need the user to visit:

redirect_uri = 'https://example.com'
permissions = 'company directory'
optional_params = { state: 'abc' }

Finch::Client::Connect.authorization_uri(redirect_uri, permissions, optional_params)

Once the user has authorized, they'll be redirected to your redirect_uri with a code query parameter. The final step in the authorization flow is to exchange this code with an access token:

redirect_uri = 'https://example.com'
code = params[:code]

Finch::Client::Connect.request_access_token(redirect_uri, code)

Once you've received the access token, you can store it for future API calls on behalf of that user. Keep in mind that you may need to handle re-authentication.

Creating a Finch API Client

Now that you have an access token you're able to configure a Finch client:

finch_client = Finch::Client::API.new(access_token)

Keep in mind that this client instance is scoped only to the provided access token. You'll need to create a new client if you want to work with a different access token.

From here, you're set to use any of the Finch APIs listed below! All objects returned from API calls respond to .headers if you need to access the raw Finch headers.

Organization APIs

Company (API Documentation)

finch_client.company

Directory (API Documentation)

# Fetches all individuals
finch_client.directory

# Per the docs you can optionally specify a limit and offset
finch_client.directory({ limit: 5, offset: 1 })

Individual (API Documentation)

# Also accepts an array of hashes - see API docs for details
individual_params = { individual_id: '...' }

finch_client.individual(individual_params)

Employment (API Documentation)

# Also accepts an array of hashes - see API docs for details
individual_params = { individual_id: '...' }

finch_client.employment(individual_params)

Payroll APIs

Payment (API Documentation)

# Fetches all payment data
finch_client.payment

# Per the docs you can optionally specify a start_date and end_date
finch_client.payment({ start_date: '2021-01-01', end_date: '2021-02-01' })

Pay Statement (API Documentation)

# Also accepts an array of hashes - see API docs for details
pay_statement_requests = { payment_id: '...' }

finch_client.pay_statement(pay_statement_requests)

Benefits APIs

Get All Benefits (API Documentation)

finch_client.benefits

Create Benefit (API Documentation)

# See API docs for details
benefit_data = {}

finch_client.create_benefit(benefit_data)

Get Benefits Metadata (API Documentation)

finch_client.benefits_metadata

Get Benefit (API Documentation)

benefit_id = '...'

finch_client.benefit(benefit_id)

Update Benefit (API Documentation)

benefit_id = '...'
# See API docs for details
benefit_data = {}

finch_client.update_benefit(benefit_id, benefit_data)

Get Enrolled Individuals (API Documentation)

benefit_id = '...'

finch_client.benefit_enrolled_individuals(benefit_id)

Get Benefits for Individual (API Documentation)

benefit_id = '...'
# Also accepts an array of strings - see API docs for details
individual_id = '...'

finch_client.benefits_for_individual(benefit_id, individual_id)

Enroll Individuals in Benefits (API Documentation)

benefit_id = '...'
# See API docs for details
enrollment_data = {}

finch_client.enroll_individual_in_benefits(benefit_id, enrollment_data)

Unenroll Individuals from Benefits (API Documentation)

benefit_id = '...'
# Also accepts an array of strings - see API docs for details
individual_id = '...'

finch_client.unenroll_individual_from_benefits(benefit_id, individual_id)

Management APIs

Introspect (API Documentation)

finch_client.introspect

Providers (API Documentation)

finch_client.providers

Disconnect (API Documentation)

finch_client.disconnect

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Percent-Pledge/finch-client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Finch::Client project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.